TopPay

Supports in this guide: Payments, Payouts

Note

No independently verifiable public website could be confirmed for this provider. The old doc's "toppay.asia" (an Indonesian payment aggregator) is a different, unrelated company - this connector processes Brazilian PIX only, confirmed from the actual API traffic in code.

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

Get your credentials (from TopPay)
Connect in Dashboard
Send an API request

Prerequisites: get from TopPay

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

Merchant ID -> Corefy field merchant_id.
Public key -> Corefy field public_key.
Private key -> Corefy field private_key -> used to sign your requests.

One Provider account is used for both Payments and Payouts. BRL only, via PIX.

Payments processing (connect Provider account, create payment-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

Merchant ID
Public key
Private key
Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected TopPay Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice and redirects the customer to TopPay's hosted PIX checkout.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "e4fdf9f3-2ca0-44d8-a6ce-97b2783dc366",
      "service": "pix_brl_hpp",
      "currency": "BRL",
      "amount": 100
    }
  }
}

Important

If none of service_fields.cpf_number, service_fields.phone, or customer.email is provided, TopPay generates the payment against a randomly generated PIX key (EVP) instead of rejecting the request.

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "8f79bad7-5387-4872-9873-12fc3866164b",
      "service": "pix_brl_hpp",
      "currency": "BRL",
      "amount": 100,
      "customer": {
        "reference_id": "9768334b-f707-4b2b-b576-2694f7c11fe0",
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+5511999999999",
        "date_of_birth": "1990-01-01"
      },
      "service_fields": {
        "cpf_number": "11111111111"
      }
    }
  }
}

Important

The customer's PIX key type is chosen by which of these is present, in this order: service_fields.cpf_number (CPF), service_fields.phone, customer.email. Only one is used; set the one that matches your customer's PIX key.
customer.name, customer.phone, customer.date_of_birth, and customer.email are all sent directly to TopPay (not through service_fields).
No Constants are configured for this connector - if a field is missing, it's simply not sent (except the PIX key fallback above).

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

Options

fail_after_payment_expiration -> optional, boolean - a payment left pending for more than 24 hours is marked as failed instead of staying pending indefinitely.

Refunds

TopPay does not support refunds.

Payouts processing (connect Provider account, create payout-invoice)

Connect Provider account in Corefy Dashboard

Uses the same Provider account connected above - no separate connection step.

First request to Corefy API (MIN)

What it does: creates a payout-invoice and sends funds to a PIX key.

Payout - MIN

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "f2ebf078-6e5e-46ba-aab8-7081d52e7917",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 100,
      "fields": {
        "account_type": "CPF",
        "cpf_number": "11111111111"
      }
    }
  }
}

Important

fields.account_type selects the PIX key type (for example CPF, EMAIL, PHONE, EVP); the matching key value field is required alongside it.

Payout - MAX

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "0682d941-de11-4bbe-a461-e44e462729a5",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 100,
      "fields": {
        "account_type": "CPF",
        "cpf_number": "11111111111",
        "beneficiary_name": "John",
        "beneficiary_lastname": "Doe"
      }
    }
  }
}

Important

fields.beneficiary_name and fields.beneficiary_lastname are both required together to send the recipient's full name - if only one is set, neither is sent.

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

Additional info

Active reconciliation is available - both Payments and Payouts support an active status request in addition to the asynchronous callback.
No recurring - this connector does not support saving/charging a token through Corefy.

FAQ / Troubleshooting

Invalid credentials / auth error -> verify the Merchant ID and key pair for the selected environment (test_mode)
Payout rejected for missing recipient name -> fields.beneficiary_name and fields.beneficiary_lastname must both be set
Payment stuck pending for a long time -> enable fail_after_payment_expiration to automatically fail payments pending more than 24 hours
Currency or service is not supported -> confirm allowed currencies/features in your TopPay account and in Corefy - only BRL via PIX is available
Refund fails -> TopPay does not support refunds through Corefy

Question

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