Skip to content

Logo

PayPaga

Payments Built For Emerging Markets

Supports in this guide: Payouts

Provider website: paypaga.com


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

  1. Choose account type
  2. Get your credentials (from PayPaga)
  3. Connect in Dashboard
  4. Send an API request

Choose account type

PayPaga can be connected in different ways (depending on your needs):

  • If you do payouts (bank transfers in Latin America) -> choose Provider account

If you are not sure which one to use, confirm with your Corefy account manager.


Prerequisites: get from PayPaga

Get the following values for your PayPaga project/account:

  • Client ID -> Corefy field client_id -> example: cl_8f2a4c71e9b34d05 -> OAuth2 client ID that Corefy uses to get an access token for PayPaga API requests. It can't be changed after the connection is created -> where to find: PayPaga backoffice / issued by PayPaga manager
  • Client Secret -> Corefy field client_secret -> example: cs_3d9e7a1b5c2f4e8a9b0d6c1f7e2a4b8d -> OAuth2 client secret used together with the Client ID to get an access token -> where to find: PayPaga backoffice / issued by PayPaga manager
  • API URL (optional) -> Corefy field api_url -> example: https://api.paypaga.com -> base URL of the PayPaga API. If left empty, Corefy uses https://api.v2.stg.paypaga.com when Test Mode is enabled and https://api.paypaga.com otherwise -> where to find: PayPaga backoffice / issued by PayPaga manager

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields (provider -> Corefy)

  • Client ID -> client_id
  • Client Secret -> client_secret
  • API URL -> api_url (optional; leave empty to use the default PayPaga URL for the selected environment)
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected PayPaga Provider account!


First request to Corefy API (MIN)

What it does: creates a payout-invoice.

Payout - MIN

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "5d2f8a1c-3e7b-4c9a-b6d4-1f0e9a2c7b38",
      "service": "bank_transfer_ars",
      "currency": "ARS",
      "amount": 100,
      "fields": {
        "account_number": "0000003100012345678901",
        "beneficiary_document_id": "20123456789"
      }
    }
  }
}

fields.account_number is the recipient's account number (CVU/CBU for Argentina), and fields.beneficiary_document_id is the recipient's document number.

Important

PayPaga also requires the payout country and the recipient's name. This MIN example works only when these values are set as Constants on the connection (country_code, first_name, last_name - see "Constants" below). Otherwise, send them in the request as shown in MAX: customer.address.country (or fields.beneficiary_country_code_iso) and customer.name. If one of them is missing in both places, PayPaga rejects the payout.

Payout - MAX

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "a7c41e9d-2b5f-4d8e-9a3c-6e1f0b7d2c54",
      "service": "bank_transfer_ars",
      "currency": "ARS",
      "amount": 100,
      "description": "Withdrawal #12345",
      "customer": {
        "reference_id": "cus_2e8b4f1a",
        "name": "John Smith",
        "email": "johnsmith@example.com",
        "phone": "5491123456789",
        "address": {
          "country": "AR",
          "full_address": "Av. Corrientes 1234, Buenos Aires"
        },
        "metadata": {
          "ip": "203.0.113.10"
        }
      },
      "fields": {
        "account_number": "0000003100012345678901",
        "beneficiary_document_id": "20123456789"
      }
    }
  }
}

How Corefy uses the MAX fields:

  • customer.reference_id -> the recipient's ID in your system (if it is missing, Corefy uses the payout ID instead). PayPaga accepts only letters, digits, -, _, @ and . in this value, up to 64 characters
  • customer.name -> the recipient's full name; Corefy also splits it into first and last name
  • customer.email, customer.phone, customer.address.full_address -> the recipient's contact details
  • customer.address.country -> the payout country (ISO 3166-1 alpha-2). You can send it in fields.beneficiary_country_code_iso instead; that field has priority
  • customer.metadata.ip -> the IP address of the customer receiving the payout (optional)
  • description -> the payout concept (purpose of the payout)

Required data per service

The set of required recipient data depends on the country. Always send the country code that matches the service (for bank_transfer_usd it is EC, Ecuador).

Service Country Required fields Required customer data
bank_transfer_ars AR account_number, beneficiary_document_id customer.name
bank_transfer_bob BO account_number, bank_code, beneficiary_document_type, beneficiary_document_id (optional: document_extension) customer.name
bank_transfer_clp CL account_number, bank_code, beneficiary_document_id customer.name, customer.email
bank_transfer_cop CO account_number, account_type, bank_name, document_type, beneficiary_document_id customer.name, customer.email, customer.phone, customer.address.full_address
bank_transfer_usd EC account_number, account_type, bank_code, beneficiary_document_type, beneficiary_document_id customer.name
bank_transfer_gtq GT account_number, account_type, beneficiary_document_type, beneficiary_document_id (optional: bank_name) customer.name, customer.email, customer.phone, customer.address.full_address
bank_transfer_mxn MX account_number, bank_code, beneficiary_document_id customer.name, description (payout concept)
bank_transfer_pen PE account_type, document_type, beneficiary_document_id (optional: account_number, bank_code) customer.name, customer.email

Customer data in this table can also come from Constants (see below), except description.


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 the provider instead of dynamic data from your API request, when those fields are missing in the request.

If a field is missing in the API request, Corefy can take the value from the configured Constants.

After the successful connection, fill in constants for necessary routes in editing menu.

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 name part)
  • last_name -> customer.name (last name part)
  • name -> customer.name
  • email -> customer.email
  • phone -> customer.phone (digits only, up to 15)
  • full_address -> customer.address.full_address
  • customer_ip -> customer.metadata.ip
  • country_code -> fields.beneficiary_country_code_iso / customer.address.country (ISO 3166-1 alpha-2, for example AR)

Refunds

PayPaga does not support refunds.


Additional info

  1. To receive callbacks, set up the callback URL in the PayPaga Merchant Portal (Developer section) or with the PayPaga API (POST /v2/notification-subscriptions), and subscribe it to the transaction_approved and transaction_failed notification types.

    • For Payouts endpoint is /paypaga/payout-callback

    Corefy verifies the signature of every callback with PayPaga's public certificates and accepts callbacks only from PayPaga notification IPs (44.197.97.108 for production, 23.21.102.219 for sandbox).

  2. A payout is created in PayPaga with the Pending status. The final status comes from PayPaga callbacks or status checks: approved -> Success; failed, rejected -> Failed; initiated, created, pending -> Pending.

  3. Insufficient balance is not reported when the payout is created. PayPaga accepts the payout first and then fails it with the wallet_failure reason.

  4. Corefy gets the balance from PayPaga for each payout currency. The available balance is the amount available for payouts in PayPaga.


FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the Client ID and Client Secret, and that Test Mode (or API URL, if set) matches the environment of your credentials (sandbox vs production)
  • Currency or service is not supported -> confirm allowed currencies/features in your PayPaga account and in Corefy
  • Payout fails with a validation error -> check the required data for the service in "Required data per service", provide missing fields in the API request or set constants (see "Constants")
  • Payout fails with the wallet_failure reason -> top up your PayPaga balance and create a new payout
  • Payout is rejected as a duplicate -> use a new reference_id for every payout
  • No callbacks are received -> check that the callback URL is set up in the PayPaga Merchant Portal with the transaction_approved and transaction_failed notification types
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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