> For the complete documentation index, see [llms.txt](https://docs.velafi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.velafi.com/api-reference/beneficiary/add-beneficiary.md). # Add Beneficiary This API allows you to add a new beneficiary for a merchant. Under the same MID and paymentId, the same receiving account can only have one valid status. #### Endpoint Information * **Request Header**: `X-BH-TOKEN: ******` * **Request Header**: `Content-Type: application/json` * **Request Method**: `POST` * **Request Path**: `/v2/payments` * **Authorization Required**: Yes #### Request Body Parameters The request body should include the following fields: ```json { "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 beneficiary) } ``` #### Authorization This request requires authorization. #### Response Structure The response will include the following fields: ```json { "code": 0, // (number: response code) "msg": "", // (string: message) "data": { // (object: result data) "id": 100, // (number: user payment ID) "status": 1, // (number: status [1: valid, 2: authenticating, 3: authentication failed]) "failReason": "", // (string: reason for authentication failure) "sameAccountNumberId": 100, // (number: There are user payment id with the same receiving account. Only when the status is 3, do we need to pay attention to this value.) } } ``` **Example Request (Mexico - MXN) 105: SPEI - FINCO PAY** ```json { "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 beneficiary" } ``` **Example Request (Mexico - MXN) 72: SPEI (Tesored)** ```json { "merchantId": 123, "paymentId": 72, "country": "Mexico", "fiat": "MXN", "realName": "John Doe", "fieldJson": { "Account Type":"clabe", //account type enum [clabe: VA account, spei_card: card account] "Full Name": "John Doe", //beneficiary name "Bank Account Number": "123456789012345678", //account number "Bank Code": "" //bank code, Only fill in when the account type is "spei_card", The list is shown in https://docs.velafi.com/api-reference/payment-method/get-payment-templates#mexico-tesored-bank-codes }, "remark": "Preferred beneficiary" } ``` **Example Request (Argentina - ARS) 63: CBU/CVU (Momentum)** ```json { "merchantId": 123, "paymentId": 63, "country": "Argentina", "fiat": "ARS", "realName": "John Doe", "fieldJson": { "CVU/CBU Number": "0000775900000000000041", //cvu/cbu account number, 22 digits "CUIT": "20339698693" //cuit, 11 digits }, "remark": "Preferred beneficiary" } ``` **Example Request (Argentina - ARS) 137: QR Argentina** ```json { "merchantId": 15123, "paymentId": 137, "country": "Argentina", "fiat": "ARS", "realName": "John Doe", "fieldJson": { "cuit": "123456789", //cuit, 11 digits "cvu/cbu":"123456789" //cvu/cbu account number, 22 digits }, "remark": "Preferred beneficiary" } ``` **Example Request (Colombia - COP)** **68: ACH/PSE** ```json { "merchantId": 15123, "paymentId": 68, "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, Maximum length: 300 "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, Maximum length: 300 "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, Maximum length: 300 }, "remark": "Preferred beneficiary" } ``` **Example Request (Colombia - COP)** **69:** Bre-B ```json { "merchantId": 15123, "paymentId": 69, "country": "Colombia", "fiat": "COP", "realName": "Tom", "fieldJson": { "brebKey": "1100000", //breb key "email": "", //email, Maximum length: 300 "phone": "" //phone, Maximum length: 300 }, "remark": "Preferred beneficiary" } ``` **Example Request (Brazil - BRL) 90: Pix (Genial)** ```json { "merchantId": 15123, "paymentId": 90, "country": "Brazil", "fiat": "BRL", "realName": "Tom", "fieldJson": { "Pix Type": "EMAIL", //enum: pix type[CPF:11 digits, CNPJ:14 digits, EMAIL:email, PHONE: 10-11 digits, RANDOM_KEY: with "-"] "Pix Key": "tom@gmail.com" //pix key, Maximum length: 100 }, "remark": "Preferred beneficiary" } ``` **Example Request (Brazil - BRL) 92: Pix - Woovi** ```json { "merchantId": 15123, "paymentId": 92, "country": "Brazil", "fiat": "BRL", "realName": "Tom", "fieldJson": { "pixType": "EMAIL", //enum: pix type[CPF:11 digits, CNPJ:14 digits, EMAIL:email, PHONE: 10-11 digits, RANDOM_KEY: with "-"] "pixKey": "tom@gmail.com" //pix key, Maximum length: 100 }, "remark": "Preferred beneficiary" } ``` **Example Request (Peru - PEN) 95: Bank Transfer** ```json { "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", //enum: 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(002-Banco de Crédito del Perú, 003-Interbank, 009-Scotiabank Perú S.A.A., 011-BBVA Continental Perú), it must be filled in. "Email": "tom@gmai.com", //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 beneficiary" } ``` **Example Request 120: Wire (CPN)** ```json { "merchantId": 15123, "paymentId": 120, "country": "United States", "fiat": "USD", "realName": "Tom", "fieldJson": { "beneficiaryName": "Tom", //name "country": "US", //nationality "stateProvince": "US-AK", //country and province code of the address location "city": "Alaska", //city "street": "789 street", //street "postalCode": "10001", //postal code "dateOfBirth": "1990-01-01", //Date of Birth or Date of Registration "idNumber": "123456", //ID Number "idExpirationDate": "2099-01-01", //expiration date "useCase": "B2B", //usd case "reasonForPayment": "PMT001", //reason for payment "bankName": "Bank of Nowhere", //bank name "bankCountry": "US", //bank country "swiftCode": "NACKUSAK001", //swift code "accountNumber": "123456" //account number }, "remark": "Preferred beneficiary" } ``` **Example Request (Hong Kong - HKD) 122: FPS (CPN)** ```json { "merchantId": 15123, "paymentId": 122, "country": "Hong Kong", "fiat": "HKD", "realName": "Tom", "fieldJson": { "beneficiaryName": "Tom", //name "country": "HK", //nationality "stateProvince": "HK-HK", //country and province code of the address location "city": "Hong Kong", //city "street": "789 street", //street "postalCode": "999077", //postal code "dateOfBirth": "1990-01-01", //Date of Birth or Date of Registration "idNumber": "123456", //ID Number "idExpirationDate": "2099-01-01", //expiration date "useCase": "B2B", //usd case "reasonForPayment": "PMT001", //reason for payment "recipientEmail": "tom@gmail.com", //recipient email "recipientPhoneNumber": "123456", //recipient phone number "fpsId": "123321", //fps id "bankCode": "999077", //bank code "accountNumber": "123456" //account number }, "remark": "Preferred beneficiary" } ``` **Example Request (Hong Kong - HKD) 123: CHATS (CPN)** ```json { "merchantId": 15123, "paymentId": 123, "country": "Hong Kong", "fiat": "Hong Kong", "realName": "Tom", "fieldJson": { "beneficiaryName": "Tom", //name "country": "HK", //nationality "stateProvince": "HK-HK", //country and province code of the address location "city": "Hong Kong", //city "street": "789 street", //street "postalCode": "999077", //postal code "dateOfBirth": "1990-01-01", //Date of Birth or Date of Registration "idNumber": "123456", //ID Number "idExpirationDate": "2099-01-01", //expiration date "useCase": "B2B", //usd case "reasonForPayment": "PMT002", //reason for payment "bankCode": "999077", //bank code "bankName": "BANK", //bank name "swiftCode": "999077", //swift code "accountNumber": "123456", //account number "recipientCity": "Hong Kong", //recipient city "recipientAddressStreet": "789 street", //recipient address street "recipientAddressCity": "Hong Kong", //recipient address city "recipientAddressCountry": "HK", //recipient address country "recipientAddressStateProvince": "HK-HK", //recipient address postal code "recipientAddressPostalCode": "999077" //recipient address postal code }, "remark": "Preferred beneficiary" } ``` **Example Request (Europe - EUR) 124: SEPA(CPN)** ```json { "merchantId": 15123, "paymentId": 124, "country": "Estonia", "fiat": "EUR", "realName": "Tom", "fieldJson": { "beneficiaryName": "Tom", //name "country": "EE", //nationality "stateProvince": "EE-37", //country and province code of the address location "city": "Estonia", //city "street": "789 street", //street "postalCode": "51004", //postal code "dateOfBirth": "1990-01-01", //Date of Birth or Date of Registration "idNumber": "123456", //ID Number "idExpirationDate": "2099-01-01", //expiration date "useCase": "B2B", //usd case "reasonForPayment": "PMT001", //reason for payment "bankName": "BANK", //bank name "bankCountry": "EE", //bank country "swiftCode": "NACKEE37001", //swift code "accountNumber": "123456" //account number }, "remark": "Preferred beneficiary" } ``` **Example Request (United States - USD) 127: FEDWIRE(CPN)** ```json { "merchantId": 15123, "paymentId": 127, "country": "France", "fiat": "EUR", "realName": "Tom", "fieldJson": { "beneficiaryName": "Tom", //name "country": "US", //nationality "stateProvince": "US-AK", //country and province code of the address location "city": "Anchorage", //city "street": "789 street", //street "postalCode": "99508", //postal code "dateOfBirth": "1990-01-01", //Date of Birth or Date of Registration "idNumber": "123456", //ID Number "idExpirationDate": "2099-01-01", //expiration date "useCase": "B2B", //usd case "reasonForPayment": "PMT001", //reason for payment "bankName": "Bank of America", //bank name "bankCountry": "US", //bank country "accountNumber": "12345678", //account number "routingNumber": "11326", //routing number "recipientCity": "Anchorage", //recipient city "recipientAddressStreet": "789 street", //recipient address street "recipientAddressCity": "Anchorage", //recipient address city "recipientAddressCountry": "US", //recipient address country "recipientAddressStateProvince": "US-AK", //recipient address postal code "recipientAddressPostalCode": "90210" //recipient address postal code }, "remark": "Preferred beneficiary" } ``` #### Success Example Response ```json { "code": 200, "msg": "SUCCESS", "data": { "id": 456, "status": 1, "failReason": "", "sameAccountNumberId": 456 } } ``` #### Account duplication Example Response The "sameAccountNumberId" indicates that the current receiving account number corresponds to the valid "userPaymentId" value. ```json { "code": 200, "msg": "SUCCESS", "data": { "id": 0, "status": 3, "failReason": "account already exists", "sameAccountNumberId": 100 } } ``` #### Notes * The `fieldJson` object 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.velafi.com/api-reference/beneficiary/add-beneficiary.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.