Add Payment Method
This API allows you to add a new payment method for a merchant.
Endpoint Information
Request Header:
X-BH-TOKEN: ******Request Header:
Content-Type: application/jsonRequest Method:
POSTRequest Path:
/v2/paymentsAuthorization Required: Yes
Request Body Parameters
The request body should include the following fields:
{
"merchantId": 0, // (number: id of the merchant id)
"paymentId": 0, // (number: payment ID)
"country": "", // (string: name of the country)
"fiat": "", // (string: name of the fiat currency)
"realName": "", // (string: real name of the account holder)
"fieldJson": { // (object: field JSON of the payment template)
[string]: [string] // (key-value pairs as per the payment template)
},
"remark": "" // (string: remark about the payment method)
}Authorization
This request requires authorization.
Response Structure
The response will include the following fields:
{
"code": 0, // (number: response code)
"msg": "", // (string: message)
"data": { // (object: result data)
"id": 0, // (number: user payment ID)
"status": 0, // (number: status [1: valid, 2: authenticating, 3: authentication failed])
"failReason": "" // (string: reason for authentication failure)
}
}Example Request (Mexico - MXN) 58: Automated SPEI - Arcus
{
"merchantId": 123,
"paymentId": 58,
"country": "Mexico",
"fiat": "MXN",
"realName": "John Doe",
"fieldJson": {
"Cuenta CLABE": "123456789012345678", //clabe number
"Banco": "Banamex", //bank name
"Beneficiary Name": "John Doe" //beneficiary name
},
"remark": "Preferred payment method"
}Example Request (Mexico - MXN) 105: SPEI - FINCO PAY
{
"merchantId": 123,
"paymentId": 105,
"country": "Mexico",
"fiat": "MXN",
"realName": "John Doe",
"fieldJson": {
"Account Type":"clabe", //account type enum [clabe: VA account, debit: card account]
"Account Number": "123456789012345678", //account number
"Beneficiary Name": "John Doe", //beneficiary name
"Bank Code": "" //bank code, Only fill in when the account type is "debit", The list is shown in https://docs.velafi.com/api-reference/payment-method/get-payment-templates#mexico-finco-pay-bank-codes
},
"remark": "Preferred payment method"
}Example Request (Argentina - ARS)
{
"merchantId": 123,
"paymentId": 63,
"country": "Argentina",
"fiat": "ARS",
"realName": "John Doe",
"fieldJson": {
"Bank Name": "Banco Galicia",
"CVU Number": "0000775900000000000041",
"CUIT": "20339698693"
},
"remark": "Preferred payment method"
}Example Request (Colombia - COP)
{
"merchantId": 15123,
"paymentId": 58,
"country": "Colombia",
"fiat": "COP",
"realName": "Tom",
"fieldJson": {
"Account Type": "cc", //enum: account type[cc: Checking Account, ch: Savings Account, dp:Electronic deposit]
"Full Name": "Tom", //full name
"ID Document Type": "cc", //enum: Type of identification document[cc: Citizenship ID, nit: Tax Identification Number, ce: Foreigner ID, pa: Pasaporte (Passport), ppt: Temporary Protection Permit, ti: Identity Card, rc: Civil Registry, te: Foreigner Card, die: Foreign Identification Document, nd: No Document]
"ID Document Number": "123456789", //Identification number
"Bank Code": "1007", //Bank Code, The list is shown in https://docs.velafi.com/api-reference/payment-method/get-payment-templates#colombian-bank-codes
"Bank Account Number": "9876543210" //Bank Account Number
},
"remark": "Preferred payment method"
}Example Request (Brazil - BRL)
{
"merchantId": 15123,
"paymentId": 90,
"country": "Brazil",
"fiat": "BRL",
"realName": "Tom",
"fieldJson": {
"Pix Type": "EMAIL", //pix type[CPF:11 digits, CNPJ:14 digits, EMAIL:email, PHONE: 10-11 digits, RANDOM_KEY: with "-"]
"Pix Key": "[email protected]" //pix key
},
"remark": "Preferred payment method"
}Example Request (Peru - PEN)
{
"merchantId": 15123,
"paymentId": 90,
"country": "Peru",
"fiat": "PEN",
"realName": "Tom",
"fieldJson": {
"Bank Name": "01", //bank code, The list is shown in https://docs.velafi.com/api-reference/payment-method/get-payment-templates#peru-bank-codes
"Account Type": "00", //account type[00:CORRIENTE, 01:AHORROS]
"Account Number": "1110333710152", //account number
"CCI Number": "", //Payer's intermediary account(20 digits), When the Bank Name is not one of the four major banks(01-BCP, 02-Interbank, 03-BBVA, 04-Scotiabank), it must be filled in.
"Email": "[email protected]", //email
"Identification Type": "00", //identification type[00:CC (8 digits), 01:CE (>9 digits), 02:Tax ID (11 digits), 03:PAS (>9 digits), 04:PAR, 05:LMI]
"Identification Number": "12345678", //identification number
"Name": "Tom", //user name
"Phone Number": "975728895" //user phone number (9 digits)
},
"remark": "Preferred payment method"
}Example Request (United States - USD)
{
"merchantId": 15123,
"paymentId": 111,
"country": "United States",
"fiat": "USD",
"realName": "Tom",
"fieldJson": {
"Account Owner Type": "individual", //account type[individual/business]
"Bank Name": "Bank of Nowhere", //bank name
"Beneficiary Name": "Tom", //name
"Email": "[email protected]", //emial
"National code": "1", //International area code for mobile phones
"Phone Number": "123456", //phone number
"Account Number": "11223344556663", //account number
"Routing Number": "123456795", //routing Number
"Street Line1": "street example", //street
"City": "New City", //city
"State": "AL", //state code
"Postal Code": "123456", //postal code
"Purpose Of Payment": "invoice_payments" //purpose of payment[invoice_payments/payment_for_services/payment_for_imported_goods/travel_services/transfer_to_own_account/repayment_of_loans/payroll/payment_of_property_rental/information_service_charges/advertising_and_public_relations/royalty_and_ip_fees/financial_service_fees/advisory_and_consulting_fees/representative_office_expenses/tax_payment/transportation_fees/construction_costs/insurance_premium/offline_goods_trade/insurance_claims/remittance_to_family_or_friends/education_expenses/medical_treatment/donations/currency_exchange/advance_payment_for_goods/merchant_settlement/repatriation_fund_settlement]
},
"remark": "Preferred payment method"
}Example Request (Hong Kong - USD)
{
"merchantId": 15123,
"paymentId": 115,
"country": "Hong Kong",
"fiat": "USD",
"realName": "Tom",
"fieldJson": {
"Account Owner Type": "individual", //account type[individual/business]
"Bank Name": "Bank of Nowhere", //bank name
"Beneficiary Name": "Tom", //name
"Date of birth or formation": "2020-01-01", //date of birth or formation
"Id Number": "123456", //id number
"Account Number": "123456789", //account number
"Swift Code": "ICEKHKHK001", //swift code
"Street Line1": "789 street", //street
"City": "Hong Kong", //city
"State": "HK", //state code
"Postal Code": "999077", //postal code
"Purpose Of Payment": "invoice_payments" ////purpose of payment[invoice_payments/payment_for_services/payment_for_imported_goods/travel_services/transfer_to_own_account/repayment_of_loans/payroll/payment_of_property_rental/information_service_charges/advertising_and_public_relations/royalty_and_ip_fees/financial_service_fees/advisory_and_consulting_fees/representative_office_expenses/tax_payment/transportation_fees/construction_costs/insurance_premium/offline_goods_trade/insurance_claims/remittance_to_family_or_friends/education_expenses/medical_treatment/donations/currency_exchange/advance_payment_for_goods/merchant_settlement/repatriation_fund_settlement]
},
"remark": "Preferred payment method"
}Example Response
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": 456,
"status": 1,
"failReason": ""
}
}Notes
The
fieldJsonobject should match the required fields for the specified payment method template.Ensure that valid authorization tokens are included in the request headers for successful execution.
Last updated