Skip to content

Logo

PayerMax

Supports in this guide: Payments

Provider website: payermax.com

What you need to do for start processing transactions (brief summary)

  1. Get your credentials (from PayerMax)
  2. Connect in Dashboard
  3. Send an API request

Prerequisites: get from PayerMax

Contact your PayerMax account manager to get your account verified and receive the following credentials.

  • Merchant ID -> Corefy field merchant_id.
  • Application ID -> Corefy field app_id.
  • Merchant private key -> Corefy field merchant_private_key -> uploaded as a file -> used to sign every outgoing request.
  • Platform public key -> Corefy field platform_public_key -> uploaded as a file -> used to verify PayerMax's callback signatures.
  • Fail after (minutes) -> Corefy field fail_after_minutes -> required when connecting -> if the payment is still pending after this many minutes, Corefy marks it as failed rather than waiting indefinitely; set to 0 to fail immediately instead of waiting at all.
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

Open PayerMax in the provider directory and press Connect at PayerMax Provider Overview page in the New connection section.

Step 2 - Fill in fields and select settings

  • Merchant ID
  • Application ID
  • Merchant private key
  • Platform public key
  • Fail after (minutes)
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected PayerMax H2H Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice; card data itself is collected and submitted separately by Corefy's checkout/SDK layer, not as part of this request.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6be05631-8710-4b14-a369-1928a2b70eda",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "address": {
          "country": "US"
        }
      }
    }
  }
}

Important

  • customer is effectively required - if the whole customer object is missing, Corefy fails the request locally before it reaches PayerMax.
  • customer.address is effectively required too whenever customer is sent at all - customer.address.country is read directly, so a customer without address also fails locally.
  • Every other field below falls back to a Dashboard Constant, and only then is simply omitted if still unset.

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "199be985-c243-478a-86a8-4b8c902e5bb6",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "email": "john@example.com",
        "phone": "+15551234567",
        "address": {
          "country": "US",
          "city": "New York",
          "region": "NY",
          "full_address": "1 Main street",
          "post_code": "10022"
        }
      }
    }
  }
}

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional customer details for compliance/reconciliation - Positively influence conversion rate - Include optional fields required by your specific flow

Constants (fallback fields)

Constants are static values that Corefy can send to PayerMax instead of dynamic data from your API request, when those fields are missing in the request.

Priority (predictable rule): 1. If a value is present in the request -> Corefy uses the request value 2. Else if the constant is set -> Corefy uses the constant 3. Else -> provider may reject the request or apply its defaults (depends on provider)

Currently available constants (constant -> Corefy API field)

  • FIRST_NAME -> customer.name (first part)
  • LAST_NAME -> customer.name (last part)
  • EMAIL -> customer.email
  • COUNTRY -> customer.address.country
  • CITY -> customer.address.city
  • REGION -> customer.address.region
  • FULL_ADDRESS -> customer.address.full_address
  • POST_CODE -> customer.address.post_code
  • PHONE -> customer.phone
  • CUSTOMER_REFERENCE_ID -> customer.reference_id

Refunds

PayerMax supports partial refunds, but only one refund per payment (no multiple partial refunds against the same payment). No original transaction ID is required to process a refund.

Additional info

  1. Active reconciliation is available - both the asynchronous callback and an active status request can finalize the payment.
  2. Callback signatures are verified - PayerMax signs every callback, and Corefy verifies it against your uploaded Platform public key before accepting it.
  3. No recurring - this connector does not support saving/charging a token through Corefy.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the Merchant ID, Application ID and key pair for the selected environment (test_mode)
  • Payment fails locally before reaching PayerMax -> make sure customer and customer.address.country are included in the request
  • Payment stuck pending, then auto-failed -> expected once the time set in Fail after (minutes) has passed
  • Refund fails with multiple attempts -> only one refund per payment is allowed

Question

Still looking for help connecting your PayerMax account? Please contact our support team!