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)
- Choose account type
- Get your credentials (from PayPaga)
- Connect in Dashboard
- 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 useshttps://api.v2.stg.paypaga.comwhen Test Mode is enabled andhttps://api.paypaga.comotherwise -> 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 characterscustomer.name-> the recipient's full name; Corefy also splits it into first and last namecustomer.email,customer.phone,customer.address.full_address-> the recipient's contact detailscustomer.address.country-> the payout country (ISO 3166-1 alpha-2). You can send it infields.beneficiary_country_code_isoinstead; that field has prioritycustomer.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):
- If a value is present in the request -> Corefy uses the request value
- Else if the constant is set -> Corefy uses the constant
- 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.nameemail->customer.emailphone->customer.phone(digits only, up to 15)full_address->customer.address.full_addresscustomer_ip->customer.metadata.ipcountry_code->fields.beneficiary_country_code_iso/customer.address.country(ISO 3166-1 alpha-2, for exampleAR)
Refunds
PayPaga does not support refunds.
Additional info
-
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 thetransaction_approvedandtransaction_failednotification 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.108for production,23.21.102.219for sandbox). - For Payouts endpoint is
-
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. -
Insufficient balance is not reported when the payout is created. PayPaga accepts the payout first and then fails it with the
wallet_failurereason. -
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_failurereason -> top up your PayPaga balance and create a new payout - Payout is rejected as a duplicate -> use a new
reference_idfor every payout - No callbacks are received -> check that the callback URL is set up in the PayPaga Merchant Portal with the
transaction_approvedandtransaction_failednotification 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!