# Authentication Source: https://developer.tazapay.com/api-reference/api-overview/authentication The Tazapay API uses [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) or `BASIC AUTH` to authenticate requests. When you sign up for an account, you can view and manage your keys on [the Tazapay dashboard](https://dashboard.tazapay.com). Tazapay API provides you with two types of keys, the API\_Key and the API\_Secret. You will need to authenticate by providing the base64 encoded key pair in the request Authorization header. Tazapay has separate keys for both test and live environments. Test keys can be generated automatically by logging into the [sandbox dashboard](https://dashboard-sandbox.tazapay.com/) and live keys by logging into the [live dashboard](https://dashboard.tazapay.com) after clearing KYB. All requests to Tazapay API must be made over HTTPS. Requests over HTTP will fail. Requests without authentication will also fail. To go from test mode to live mode, you need to change the endpoint URL along with changing the API keys. **API\_Secret key is "secret" for a reason!** Do not share your API keys to any unauthorised parties. This includes publicly accessible areas such as GitHub, client-side code, etc. An unauthorised party can create transactions on your behalf if they get a hold of your API keys. ### How to Authenticate 1. `BASIC AUTH` requires a username and a password combined with a colon. Its format is **username:password**. **NOTE:** Your API\_Key will serve as the username and the API\_Secret as the password. 2. The resultant value is encoded into a [Base64](https://en.wikipedia.org/wiki/Base64) format. 3. Prefix the Base64 encoded value with **Basic** and pass it in the *Authorization* header. ### Example 1. If your API keys are: ```text API Keys theme={null} API_Key : F2W7H8JWMO8398KAPW85 API_Secret : rKHFAffLq5Lnrms3mOBQi71oQmMATH2EByYDyIR2Wd0jGdKeed08WThGVS6v1257 ``` 2. Following the `BASIC AUTH` format, the value generated is: ```text BASIC AUTH format theme={null} F2W7H8JWMO8398KAPW85:rKHFAffLq5Lnrms3mOBQi71oQmMATH2EByYDyIR2Wd0jGdKeed08WThGVS6v1257 ``` 3. [Encoding the above value](https://www.base64encode.org/) into Base64, the resultant value generated is: ```text Base64 value theme={null} RjJXN0g4SldNTzgzOThLQVBXODU6cktIRkFmZkxxNUxucm1zM21PQlFpNzFvUW1NQVRIMkVCeVlEeUlSMldkMGpHZEtlZWQwOFdUaEdWUzZ2MTI1Nw== ``` 4. Include this Base64 value in the Authorization header with Basic prefix: ```text Authorization header theme={null} Authorization: Basic RjJXN0g4SldNTzgzOThLQVBXODU6cktIRkFmZkxxNUxucm1zM21PQlFpNzFvUW1NQVRIMkVCeVlEeUlSMldkMGpHZEtlZWQwOFdUaEdWUzZ2MTI1Nw== ``` # Endpoints and Environments Source: https://developer.tazapay.com/api-reference/api-overview/endpoints-and-environments Tazapay API is served over HTTPS and unencrypted HTTP connections are not supported. Tazapay API has the following endpoints: **Live mode (Production)** This is our Live environment where we process real transactions and actual money movement happens. You will need to use the following URL for all live mode API calls: `https://service.tazapay.com`. Sign up or log in at [dashboard.tazapay.com](https://dashboard.tazapay.com). **Test Mode (Sandbox)** You can use this environment to test the transactions and workflows before going Live. You will need to use the following URL for all sandbox API calls: `https://service-sandbox.tazapay.com`. Access the sandbox at [dashboard-sandbox.tazapay.com](https://dashboard-sandbox.tazapay.com). The Tazapay API docs allow you to test our API. While using the docs to test APIs, you are using our test environment. Money movement, actual verification of documents and KYB processes will not be available in Sandbox. If needed, we can work with you to mock success and failure responses for specific APIs to test the end to end flow. Please drop a note on [support@tazapay.com](mailto:support@tazapay.com) with your request. For testing real movement of money, you can initiate a transaction in Live mode. # Idempotent Requests Source: https://developer.tazapay.com/api-reference/api-overview/idempotent-requests Safely retry API requests Tazapay API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for safely retrying POST requests ensuring that you do not perform the same operation twice. This is useful when an API call is in transit and you do not receive a response. For example, if the request to create a transaction does not give a response, the same request can be successfully retried by using the same idempotency key in the header of the request. Tazapay's idempotency works by storing the responses associated with successful requests, that is, requests which generate a 2xx status code. When you pass the same idempotency key in the header of the request body, the saved response is returned without performing the same operation again. If the request does not generate a successful response, passing the same idempotency key will cause it to perform the operation again. If the API returns an error, the response is not stored and the operation is executed again. We recommend passing idempotency keys only with POST requests. Passing idempotency keys with GET has no effect. To make idempotent requests, pass the following header with the request. ```text Header theme={null} "Idempotency-Key":"afaowwWEshsfnosfnlsf" ``` You can pass a maximum of 255 characters in the value for the idempotency key. An idempotency key is a unique value generated by the client which the Tazapay server uses to recognise retries of the same request. You must ensure that you choose a method that generates keys with sufficient variations so that they are not same to another previous key passed. Any idempotency key is valid for a period of 24 hours from the time the request hits Tazapay's servers and it starts executing. If no execution happened, the key is not stored. Moreover, after 24 hours, any request with the same idempotency key is treated as a new request. # Introduction Source: https://developer.tazapay.com/api-reference/api-overview/introduction Welcome to the Tazapay API The Tazapay API is organised around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. You can use the Tazapay API in test mode, which doesn't affect your live data or interact with the payment rails. The API key you use in combination with the endpoint URL determine whether the request is in live mode or test mode. # Webhooks Source: https://developer.tazapay.com/api-reference/api-overview/webhooks Receive real-time notifications via webhooks Webhook Endpoints are setup on an account level from the dashboard as that gives users an interface to look at any successful or failed webhooks requests and also re-trigger them if required. Use this [guide](/api-reference/appendix/webhooks-guide) to setup webhooks. It is necessary that you configure your endpoint URL to acknowledge Tazapay's webhooks with standard HTTP Codes. For example, pass 2xx for a successful POST request receipt on your server. If Tazapay does not receive a 2xx acknowledgement, it will retry sending webhooks to the endpoint for a period of 24 hours. Click [here](/api-reference/appendix/webhook-retry-policy) for the detailed retry policy. In case of any server block or not receiving a response to your webhook URL, try whitelisting the below IP addresses: * Test Mode (Sandbox): **13.213.226.109** * Live Mode (Production): **52.77.198.235** # ABA Routing Number Validation Source: https://developer.tazapay.com/api-reference/appendix/aba-routing-number-validation ABA routing numbers are 9-digit codes used to identify financial institutions in the United States. They use the **ABA 3-7-1 checksum algorithm** for validation. ## ABA 3-7-1 Checksum Algorithm The routing number is valid if the weighted sum is **divisible by 10** (modulo 10 = 0). ### Validation Steps **Step 1**: Multiply each digit by its weight Each digit position has a specific weight: **3, 7, 1, 3, 7, 1, 3, 7, 1** **Example**: `021000021` ``` (0 × 3) + (2 × 7) + (1 × 1) + (0 × 3) + (0 × 7) + (0 × 1) + (0 × 3) + (2 × 7) + (1 × 1) = 0 + 14 + 1 + 0 + 0 + 0 + 0 + 14 + 1 = 30 ``` **Step 2**: Calculate modulo 10 ``` 30 mod 10 = 0 ``` **Step 3**: Validate * **If remainder = 0**: Routing number is valid ✓ * **If remainder ≠ 0**: Routing number is invalid ✗ ## Implementation in Go ```go theme={null} package main import "fmt" func ValidateABARoutingNumber(aba string) bool { // Must be exactly 9 digits if len(aba) != 9 { return false } // 3-7-1 checksum algorithm: // Multiply positions 1,4,7 by 3; positions 2,5,8 by 7; positions 3,6,9 by 1 // Sum all results — modulo 10 must equal 0 d := func(i int) int { return int(aba[i] - '0') } sum := 3*(d(0)+d(3)+d(6)) + 7*(d(1)+d(4)+d(7)) + 1*(d(2)+d(5)+d(8)) return sum%10 == 0 } func main() { testCases := []struct { routingNumber string valid bool }{ {"021000021", true}, // Chase Bank {"111000025", true}, // Bank of America {"123456789", false}, // Invalid checksum } for _, tc := range testCases { result := ValidateABARoutingNumber(tc.routingNumber) status := "✓" if !result { status = "✗" } fmt.Printf("%s %s (expected: %v)\n", status, tc.routingNumber, tc.valid) } } ``` ## Related Resources * [Create Beneficiary API](/api-reference/tazapay-api/create-beneficiary) * [Create Payout API](/api-reference/tazapay-api/create-payout) * [Field Validation Updates](/changelog/2026/field-validation-updates) # Add Billing/Shipping Source: https://developer.tazapay.com/api-reference/appendix/add-billing-shipping Error codes for POST /v3/customer/{id}/{type} ### POST v3/customer/\{id}/\{type} | Code | Message | HTTP Status | | ---- | --------------------------- | ----------- | | 2313 | Customer id is missing | 400 | | 2314 | Address type is missing | 400 | | 2315 | Address details are missing | 400 | | 2316 | Line 1 address is invalid | 400 | | 2317 | City is invalid | 400 | | 2318 | State is invalid | 400 | | 2319 | Country is invalid | 400 | | 2320 | Postal code is invalid | 400 | # Address Validation Source: https://developer.tazapay.com/api-reference/appendix/address-validation Ensure correct input from customers to increase conversion It is mandatory to ensure the following validations for the billing address for customers in United States of America (US) and Canada (CA). This is applicable to: 1. `/v3/checkout` 2. `/v3/escrow` 3. `/v3/payin` 4. `confirmPayment()` (Javascript SDK) ## Validations | Field | Validation | Applicable for countries | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `billing_details.address.country` | ISO 3166-1 alpha-2 country code (in uppercase) | US, CA | | `billing_details.address.line1` | Min 4 characters, only alphanumeric characters allowed | US, CA | | `billing_details.address.city` | Only alphanumeric characters allowed | US, CA | | `billing_details.address.state` | Only alphanumeric characters allowed | US, CA | | `billing_details.address.state` | 2-letter State/Province code (ISO 3166-2). The state names and code can be accessed from [this list for US](https://www.iso.org/obp/ui/#iso:code:3166:US) and [this list for CA](https://en.wikipedia.org/wiki/ISO_3166-2:CA) | US, CA | | `billing_details.address.postal_code` | For US, valid length is 5 or 9 and the format is NNNNN. For CA, valid length is 6 and the format is ANA NAN (A = Alphabet, N = Number) | US, CA | | `billing_details.phone.calling_code` | Only codes from [this list](https://en.wikipedia.org/wiki/List_of_country_calling_codes) | US, CA | | `billing_details.phone.number` | Only numeric values allowed. Length allowed: USA: 10, Canada: 10 | US, CA | # Cancel Payin Source: https://developer.tazapay.com/api-reference/appendix/cancel-payin Error codes for POST /v3/payin/{id}/cancel ### POST v3/payin/\{id}/cancel | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------------------------------------------------- | ----------- | | 15550 | Payin Id is required. Please check whether id provided is in correct format. Example: chk\_id/esc\_id/pay\_id/col\_id | 400 | | 15550 | Payin Id is required. Please check whether id provided is in correct format. Example: chk\_id/esc\_id/pay\_id/col\_id | 404 | | 19626 | The payin is either no longer active or has been cancelled | 409 | | 19627 | The payin is currently in an invalid state for cancellation. | 409 | # Cancel Refund Source: https://developer.tazapay.com/api-reference/appendix/cancel-refund Error codes for POST /v3/refund/{id}/cancel ### POST v3/refund/\{id}/cancel | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------------------------------- | ----------- | | 30050 | Invalid refund\_id, should have prefix 'rfd\_' and should be followed by valid xid | 400 | | 30150 | Cannot cancel a refund object at this stage. | 400 | # Collection Methods Source: https://developer.tazapay.com/api-reference/appendix/collection-methods Error codes for GET /v3/metadata/collect ### GET v3/metadata/collect | Code | Message | HTTP Status | | ---- | ------------------------------------------------------------------------------------------- | ----------- | | 1000 | country %s is not supported at this moment | 400 | | 1006 | account country %s is not supported at this moment | 404 | | 1007 | customer country %s is not supported at this moment | 404 | | 1011 | given currency %s is not supported | 404 | | 1030 | The requested invoice currency is not supported in the customer/account country's corridor. | 400 | # Confirm Payin Source: https://developer.tazapay.com/api-reference/appendix/confirm-payin Error codes for POST /v3/payin/{id}/confirm ### POST v3/payin/\{id}/confirm | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------------------------------- | ----------- | | 15508 | Please provide a valid URL | 400 | | 15512 | Number field in phone is required and should be a valid value | 400 | | 15526 | Payin Id is required. Please check whether id provided is in correct format. Example: pay\_id | 400 | | 15526 | Payin Id is required. Please check whether id provided is in correct format. Example: pay\_id | 404 | | 15527 | Please provide a valid customer id | 400 | | 15554 | Please provide a valid charge currency | 400 | | 19003 | Customer country not enabled for transaction | 400 | | 19017 | Payin status is not in valid state to initiate payment | 409 | | 19623 | Either customer details or customer id is mandatory | 400 | | 19624 | Payment method details are mandatory for payin confirmation. | 400 | | 19625 | Card payment method is not supported by the API | 400 | | 19626 | The payin is either no longer active or has been cancelled | 409 | | 19628 | Tax ID entered is invalid. Please enter a valid tax ID | 400 | | 19630 | CURP entered is invalid. Please provide a valid CURP number | 400 | | 19631 | RFC entered is invalid. Please provide a valid RFC number | 400 | | 19632 | The customer\_type entered is invalid. Valid customer\_type can be either of individual or business | 400 | | 19633 | curp cannot be empty. curp is a mandatory field for individual customer\_type | 400 | | 19634 | rfc cannot be empty. rfc is a mandatory field for bank\_push\_mxn | 400 | | 19710 | Please provide a valid issuing country | 400 | | 19620 | Unable to proceed, no payment methods found for processing the transaction. | 400 | | 19621 | Unable to confirm payin, payment method currency is not same as the invoice currency. | 400 | # Confirm Payout Source: https://developer.tazapay.com/api-reference/appendix/confirm-payout Error codes for POST /v3/payout/{id}/confirm ### POST v3/payout/\{id}/confirm | Code | Message | HTTP Status | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 20195 | Field is required and must be a valid payout\_id | 400 | | 20390 | Field cannot be empty, must be a valid transaction hash | 400 | | 20391 | Field must be either 'balance' or a valid xid type with prefix 'col\_' | 400 | | 20392 | Transaction hash already used for other payment, please try again with different transaction hash. | 400 | | 20393 | Payout status is invalid to perform this action, payout has moved to higher status. | 409 | | 20394 | The collect created is already linked to a payout. Please try with different collect id or transaction hash. | 400 | | 20395 | The transaction hash provided is not valid or mismatched with collect id. Please try with different transaction hash. | 400 | | 20396 | The balance impact or the currency of the collect does not match with the payout. Please try with different transaction hash or collect id. | 400 | | 20397 | The account ID of the payout does not match the account ID of the collect. Please ensure both transactions belong to the same account. | 401 | | 20398 | Collect status is invalid to perform this action | 400 | | 20399 | Payout status is invalid to perform this action, payout was not funded within the time limit and has failed. | 409 | | 20631 | Holding currency of payout and collect do not match | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | -------------------------- | ----------- | | 4008 | Invalid quote\_id provided | 400 | | 4304 | FX quote not found | 404 | # Converting the QR code to image Source: https://developer.tazapay.com/api-reference/appendix/converting-the-qr-code-to-image Steps to convert the API qr_code response into a renderable image 1. **Get QR Code** Get the `qr_code` value from the API response. 2. **Basic Decode** Decode the `qr_code` data, which is encoded using Base64. Example, in JS: ```jsx theme={null} const decodedQrCode = window.atob(qr_code); ``` 3. **Convert to QR Image URL** Use any known method in your programming language, or an external library, to convert `decodedQrCode` into a QR image URL. Example using the [qrcode](https://www.npmjs.com/package/qrcode) npm package (ES6/ES7): ```jsx theme={null} import QRCode from 'qrcode' let qr_url = null; // With promises QRCode.toDataURL(decodedQrCode) .then((url) => { console.log(url) qr_url = url; }) .catch((err) => { console.error(err) }) ``` 4. **Render QR Image** Set `qr_url` as the `src` attribute of an image element in HTML. Example: ```jsx theme={null} QR image ``` # Create Beneficiary Source: https://developer.tazapay.com/api-reference/appendix/create-beneficiary Error codes for POST /v3/beneficiary ### POST v3/beneficiary | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 20150 | Field is required, please provide a valid name | 400 | | 20151 | Please provide a valid email address | 400 | | 20152 | Please provide a valid type | 400 | | 20153 | Please provide a valid beneficiary\_details | 400 | | 20154 | Please provide a valid bank\_name | 400 | | 20155 | Please provide a valid country. Must be alpha-2 country code. Ex: IN, SG | 400 | | 20156 | Please provide a valid currency | 400 | | 20157 | Please provide a valid bank codes | 400 | | 20158 | Please provide a valid payout\_wallet deposit\_address | 400 | | 20159 | Bank payout functionality is currently disabled. Please contact support for assistance. | 400 | | 20160 | Wallet payout functionality is currently disabled. Please contact support for assistance. | 400 | | 20320 | Please provide the common bank fields to create a payout either through local or swift: %s | 400 | | 20321 | Please provide all the valid bank local\_fields to create a local payout: %s | 400 | | 20322 | Please provide all the valid bank swift\_fields to create a swift payout: %s | 400 | | 20326 | Invalid bank fields. Please provide a valid value for following fields: %s | 400 | | 20361 | Please provide the missing required beneficiary fields: %s | 400 | | 3895 | Account number is required and cannot be empty | 400 | | 3896 | Account number must be alphanumeric and between 4-34 characters | 400 | | 3900 | IBAN is required and cannot be empty | 400 | | 3901 | IBAN must be between 15-34 characters | 400 | | 3902 | IBAN must be between 15-34 characters and start with 2 letters, 2 digits, followed by alphanumeric characters | 400 | | 3903 | IBAN country code is not supported | 400 | | 3904 | IBAN country code does not match the destination country code | 400 | | 3905 | IBAN length is invalid for the specified country | 400 | | 3906 | IBAN checksum validation failed. Please verify that the IBAN is correct | 400 | | 3907 | IBAN country code is not supported by Tazapay | 400 | | 3910 | SWIFT code is required and cannot be empty | 400 | | 3911 | SWIFT code must be either 8 or 11 characters with format: 4 letters (bank), 2 letters (country), 2 alphanumeric (location), and optional 3 alphanumeric (branch) | 400 | | 3912 | SWIFT code has invalid location code. Characters 7 and 8 cannot be '00' | 400 | | 3913 | SWIFT country code is not supported by Tazapay | 400 | | 3915 | BIC code is required and cannot be empty | 400 | | 3916 | BIC code must be either 8 or 11 characters with format: 4 letters (bank), 2 letters (country), 2 alphanumeric (location), and optional 3 alphanumeric (branch) | 400 | | 3917 | BIC code has invalid location code. Characters 7 and 8 cannot be '00' | 400 | | 3918 | BIC country code is not supported by Tazapay | 400 | | 3920 | Sort code is required and cannot be empty | 400 | | 3921 | Sort code must be exactly 6 numeric digits | 400 | | 3925 | ABA routing number is required and cannot be empty | 400 | | 3926 | ABA routing number must be exactly 9 numeric digits | 400 | | 3927 | ABA routing number has invalid federal reserve prefix (first 2 digits) | 400 | | 3928 | ABA routing number checksum validation failed (3-7-1 algorithm) | 400 | | 3930 | IFSC code is required and cannot be empty | 400 | | 3931 | IFSC code must be exactly 11 characters (4 letters, '0', 6 alphanumeric) | 400 | | 3935 | BSB code is required and cannot be empty | 400 | | 3936 | BSB code must be exactly 6 numeric digits | 400 | | 3940 | Bank code (Brazil) is required and cannot be empty | 400 | | 3941 | Bank code (Brazil) must be either 3 digits (COMPE) or 8 digits (ISPB) | 400 | # Create Checkout Source: https://developer.tazapay.com/api-reference/appendix/create-checkout Error codes for POST /v3/checkout ### POST v3/checkout | Code | Message | HTTP Status | | ----- | ------------------------------------------------------------------------------------------------ | ----------- | | 15503 | The requested invoice currency is not supported in the customer/account country's corridor. | 400 | | 15504 | Field is required and value must be greater than 0 | 400 | | 15511 | Payment link expiry can not be less than current time | 400 | | 15512 | Number field in phone is required and should be a valid value | 400 | | 15523 | Sum of amount in transaction data should be less than or equal to payin amount | 400 | | 15524 | Please provide a valid date format dd-mm-yyyy, example- 20-10-2023 | 400 | | 15525 | Please provide a valid payment type, it can be either deposit or balance | 400 | | 15528 | The amount passed in the invoice amount does not match the sum of the amounts provided for items | 400 | | 15531 | Maximum allowed date range is 60 days | 400 | | 19003 | Customer country not enabled for transaction | 400 | | 19006 | Customer details not available | 400 | | 19007 | Account details not available | 400 | | 19009 | Parties should not be identical | 400 | | 19012 | There are no payment methods to serve this txn | 400 | | 19013 | Can not remove payment method specified in payment methods | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | ---------------------------------- | ----------- | | 4000 | Invalid from currency provided | 400 | | 4001 | Invalid to currency provided | 400 | | 4012 | Invalid from\_amount provided | 400 | | 4027 | Non-fiat currency is not supported | 400 | # Create Customer Source: https://developer.tazapay.com/api-reference/appendix/create-customer Error codes for POST /v3/customer ### POST v3/customer | Code | Message | HTTP Status | | ---- | ------------------------------------------ | ----------- | | 2300 | Country is missing | 400 | | 2301 | Account id is missing | 400 | | 2302 | Email is missing | 400 | | 2303 | Calling code is missing | 400 | | 2304 | Phone.number is missing | 400 | | 2305 | Please send valid metadata | 400 | | 2321 | Name should not contain special characters | 400 | # Create Entity Source: https://developer.tazapay.com/api-reference/appendix/create-entity Error codes for POST /v3/entity ### POST v3/entity | Code | Message | HTTP Status | | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 3003 | Business is required field | 400 | | 3006 | A required field is missing, check our KYB API body parameters for required fields | 400 | | 3007 | Please provide business incorporation\_no | 400 | | 3008 | Please provide document sub type | 400 | | 3009 | User not found | 404 | | 3010 | Account is a required field | 400 | | 3011 | Entity\_name is required field | 400 | | 3013 | Please provide country | 400 | | 3014 | Please provide annual turnover | 400 | | 3016 | Type is required field | 400 | | 3017 | Please pass a valid URL for download. Ensure that this is a downloadable file. | 400 | | 3018 | Please pass a valid UUID for account. Refer to Post KYB body parameters | 400 | | 3019 | Unable to update since the KYB is already completed. please contact us at [ops@tazapay.com](mailto:ops@tazapay.com) if there is a change in the entity's details. | 400 | | 3020 | You are not allowed to use this name. Please try another business name | 400 | | 3021 | Representative is required field | 400 | | 3022 | Owner is required field. Please provide at least one owner | 400 | | 3023 | Please provide address | 400 | | 3024 | Please provide documents | 400 | | 3036 | We regret to inform you that you currently do not have the necessary authorization to access this resource | 403 | | 3000 | KYB application already exists, please update existing details | 409 | # Create Lightning Invoice Source: https://developer.tazapay.com/api-reference/appendix/create-lightning-invoice Error codes for POST /v3/lightning_invoice_bolt11 ### POST v3/lightning\_invoice\_bolt11 | Code | Message | HTTP Status | | ----- | ----------------------------------------------------------------------- | ----------- | | 20470 | Please provide a valid invoice amount | 400 | | 20472 | Invoice status is invalid for this operation | 400 | | 20473 | Please provide a valid expiry interval | 400 | | 20474 | Please provide a valid metadata | 400 | | 20475 | h\_tag\_memo must be exactly 64 characters long for a valid SHA256 hash | 400 | | 20476 | h\_tag\_memo must contain only hexadecimal characters (0-9, a-f, A-F) | 400 | | 20477 | Please provide the d\_tag\_memo with valid length | 400 | # Create Payin Source: https://developer.tazapay.com/api-reference/appendix/create-payin Error codes for POST /v3/payin ### POST v3/payin | Code | Message | HTTP Status | | ----- | ------------------------------------------------------------- | ----------- | | 15501 | Please provide a valid email address | 400 | | 15502 | Please provide a valid country | 400 | | 15504 | Please provide a valid amount | 400 | | 15505 | Field is required and must be a valid value | 400 | | 15507 | Please provide a valid fee percentage | 400 | | 15508 | Please provide a valid URL | 400 | | 15509 | Please provide a valid transaction description | 400 | | 15510 | Customer details are required | 400 | | 15511 | Please provide a valid expiry time | 400 | | 15512 | Number field in phone is required and should be a valid value | 400 | | 15513 | Please provide a valid transaction source category | 400 | | 15522 | Please provide a valid postal code | 400 | | 15529 | Please provide a valid quantity | 400 | | 19001 | Please provide a valid invoice currency code | 400 | | 19623 | Either customer details or customer id is mandatory | 400 | | 19624 | Payment method details are mandatory for payin confirmation. | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | ---------------------------------- | ----------- | | 4000 | Invalid from currency provided | 400 | | 4001 | Invalid to currency provided | 400 | | 4012 | Invalid from\_amount provided | 400 | | 4027 | Non-fiat currency is not supported | 400 | | 4303 | Base rate not found | 404 | | 4308 | Live base rate not found | 404 | # Create Payout Source: https://developer.tazapay.com/api-reference/appendix/create-payout Error codes for POST /v3/payout ### POST v3/payout | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 20003 | Please provide a valid amount | 400 | | 20028 | Please provide beneficiary name in Chinese | 400 | | 20029 | Please provide valid beneficiary national identification number | 400 | | 20030 | Field is required and must be valid logistic tracking details | 400 | | 20035 | Transaction not allowed as the ultimate remitter and beneficiary are in the same region and is restricted. | 400 | | 20036 | Account holder name is required and cannot be empty | 400 | | 20037 | When the txn source is bfi, funding interval should be configured please configure funding interval and try again later | 400 | | 20038 | Both holding\_fx\_quote and destination\_fx\_quote cannot be provided | 400 | | 20039 | The amount locked in fx quote is not the same as the amount in request | 400 | | 20040 | this purpose code is not supported for the Remitter and Beneficiary type combination | 400 | | 20041 | Invalid source for providing destination\_info | 400 | | 20042 | EURC currency is not supported | 400 | | 20043 | Mismatch detected: The provided destination currency does not align with our system records | 400 | | 20044 | Non-fiat currency is not supported or invalid | 400 | | 20045 | Business-to-business payouts are not permitted for Pakistan. Please select an eligible remitter or beneficiary type. | 400 | | 20061 | Field is required and must be valid ISO 4217 alpha-3 currency code | 400 | | 20067 | Holding currency not found for the specified account. | 400 | | 20152 | Please provide a valid type | 400 | | 20165 | Please provide either the beneficiary details or a beneficiary ID. One of these fields is mandatory for processing. | 400 | | 20166 | Payout risk is not enabled to initiate payout | 400 | | 20167 | Please provide a valid payout currency | 400 | | 20168 | Please provide a valid holding currency | 400 | | 20170 | Payout creation failed: The bank transfer type is swift, which is incompatible with the local payout type | 400 | | 20171 | Please provide a valid purpose code to create payout | 400 | | 20172 | The requested payout type does not match the beneficiary destination type | 400 | | 20173 | The requested beneficiary is not associated with the account | 400 | | 20174 | Please provide valid transaction source | 400 | | 20175 | Payout invoice document is not found. Please provide valid invoice document | 400 | | 20196 | Field on\_behalf\_of is required for creating this payout | 400 | | 20197 | Please provide valid on\_behalf\_of, should be valid xid type with prefix ent\_ | 400 | | 20198 | Entity doesn't match with tazapay compliance policy. Please contact us at [ops@tazapay.com](mailto:ops@tazapay.com) | 400 | | 20199 | There is insufficient balance in your account to make the desired payout. Please ensure you have added sufficient funds to your account before retrying. | 400 | | 20201 | Payout failed: No available provider for the data provided. The following fields are required by our network for this destination: %s | 400 | | 20231 | Field is required and must be a valid document type. | 400 | | 20283 | Provided document is not sufficient to create payout | 400 | | 20296 | Requested payout config is not supported, please check the payout config | 400 | | 20298 | The specified transaction amount does not meet the required minimum or maximum limits. | 400 | | 20299 | Please provide a valid quote, payout or fx quote is expired or mismatch in from and to currency | 400 | | 20380 | Mismatch detected: The provided beneficiary registration number does not align with our system records | 400 | | 20381 | Mismatch detected: The provided beneficiary business name does not align with our system records | 400 | | 20382 | Mismatch detected: The provided beneficiary business address country does not align with our system records | 400 | | 20383 | Beneficiary date of birth is required and can't be empty when beneficiary type is individual | 400 | | 20384 | Third Party Wallet payout functionality is currently disabled. Please contact support for assistance. | 400 | | 20385 | Beneficiary registration number is required and can't be empty | 400 | | 20386 | Beneficiary address details are required and can't be empty | 400 | | 20387 | Beneficiary party classification is required, please pass valid party classification | 400 | | 20388 | Mismatch detected: The provided individual name does not align with our system records | 400 | | 20389 | Individual business must be a sole proprietorship | 400 | | 20400 | Mismatch detected: The provided date of birth does not align with our system records | 400 | | 20401 | VASP name is required for wallet beneficiary | 400 | | 20403 | This wallet beneficiary is not yet approved, please get your beneficiary approved before creating a payout | 400 | | 20426 | Field is required and must be a valid payout\_quote\_id | 400 | | 20427 | Payout Quote cannot be validated if either holding\_fx\_quote or destination\_fx\_quote is present | 400 | | 20428 | Payout quote mismatch with Create Payout request | 400 | | 20434 | Please provide a valid payout quote, payout quote is expired | 400 | | 20437 | Please provide a valid destination\_fx\_quote starting with 'fx\_' | 400 | | 20438 | Please provide a valid quote starting with 'poq\_' | 400 | | 20643 | Please provide a valid holding\_fx\_quote starting with 'fx\_' | 400 | | 3895 | Account number is required and cannot be empty | 400 | | 3896 | Account number must be alphanumeric and between 4-34 characters | 400 | | 3900 | IBAN is required and cannot be empty | 400 | | 3901 | IBAN must be between 15-34 characters | 400 | | 3902 | IBAN must be between 15-34 characters and start with 2 letters, 2 digits, followed by alphanumeric characters | 400 | | 3903 | IBAN country code is not supported | 400 | | 3904 | IBAN country code does not match the destination country code | 400 | | 3905 | IBAN length is invalid for the specified country | 400 | | 3906 | IBAN checksum validation failed. Please verify that the IBAN is correct | 400 | | 3907 | IBAN country code is not supported by Tazapay | 400 | | 3910 | SWIFT code is required and cannot be empty | 400 | | 3911 | SWIFT code must be either 8 or 11 characters with format: 4 letters (bank), 2 letters (country), 2 alphanumeric (location), and optional 3 alphanumeric (branch) | 400 | | 3912 | SWIFT code has invalid location code. Characters 7 and 8 cannot be '00' | 400 | | 3913 | SWIFT country code is not supported by Tazapay | 400 | | 3915 | BIC code is required and cannot be empty | 400 | | 3916 | BIC code must be either 8 or 11 characters with format: 4 letters (bank), 2 letters (country), 2 alphanumeric (location), and optional 3 alphanumeric (branch) | 400 | | 3917 | BIC code has invalid location code. Characters 7 and 8 cannot be '00' | 400 | | 3918 | BIC country code is not supported by Tazapay | 400 | | 3920 | Sort code is required and cannot be empty | 400 | | 3921 | Sort code must be exactly 6 numeric digits | 400 | | 3925 | ABA routing number is required and cannot be empty | 400 | | 3926 | ABA routing number must be exactly 9 numeric digits | 400 | | 3927 | ABA routing number has invalid federal reserve prefix (first 2 digits) | 400 | | 3928 | ABA routing number checksum validation failed (3-7-1 algorithm) | 400 | | 3930 | IFSC code is required and cannot be empty | 400 | | 3931 | IFSC code must be exactly 11 characters (4 letters, '0', 6 alphanumeric) | 400 | | 3935 | BSB code is required and cannot be empty | 400 | | 3936 | BSB code must be exactly 6 numeric digits | 400 | | 3940 | Bank code (Brazil) is required and cannot be empty | 400 | | 3941 | Bank code (Brazil) must be either 3 digits (COMPE) or 8 digits (ISPB) | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ----- | ------------------------------------------- | ----------- | | 2051 | Metadata config not found for the account | 400 | | 2052 | Risk config not found for the account | 400 | | 2053 | Config not supported for this account type | 500 | | 2062 | Account ID is missing or invalid | 400 | | 2820 | KYB is in dormant state for this account | 403 | | 2821 | KYB is in terminated state for this account | 403 | | 3533 | Invalid beneficiary type provided | 400 | | 4000 | Invalid from currency provided | 400 | | 4001 | Invalid to currency provided | 400 | | 4004 | Invalid FX config provided | 400 | | 4005 | Invalid FX type provided | 400 | | 4006 | Invalid account\_id provided | 400 | | 4007 | Invalid admin\_id provided | 400 | | 4009 | Invalid collection currency provided | 400 | | 4010 | Invalid customer country provided | 400 | | 4011 | Invalid payment method family provided | 400 | | 4012 | Invalid from\_amount provided | 400 | | 4027 | Non-fiat currency is not supported | 400 | | 4303 | Base rate not found | 404 | | 4308 | Live base rate not found | 404 | | 5090 | Invalid account\_id provided (pricing) | 400 | | 5091 | Invalid payout transfer type | 400 | | 5092 | Invalid destination currency code | 400 | | 5093 | Invalid destination amount | 400 | | 5094 | Invalid payout currency code | 400 | | 5095 | Invalid payout amount | 400 | | 5096 | Invalid payout wallet type | 400 | | 5097 | Invalid payout quote\_id | 400 | | 5098 | Invalid charge type | 400 | | 43000 | Invalid country provided | 400 | | 43001 | Invalid currency provided | 400 | | 43014 | Invalid bank transfer type provided | 400 | # Create Payout Quote Source: https://developer.tazapay.com/api-reference/appendix/create-payout-quote Error codes for POST /v3/payout/quote ### POST v3/payout/quote | Code | Message | HTTP Status | | ----- | ----------------------------------------------------------------------------------------------------- | ----------- | | 20002 | Please provide a valid amount | 400 | | 20066 | Holding currency not found for the specified account. | 400 | | 20248 | Please provide a valid currency | 400 | | 20270 | Please provide a valid holding currency | 400 | | 20274 | The requested payout type does not match the beneficiary destination type | 400 | | 20296 | Requested payout config is not supported, please check the payout config | 400 | | 20298 | The specified transaction amount does not meet the required minimum or maximum limits. | 400 | | 20420 | Please provide any one of holding\_info.amount, payout\_info.amount or destination\_info.amount | 400 | | 20421 | Field is required and must be a valid destination\_country | 400 | | 20422 | Please provide a valid charge\_type | 400 | | 20423 | Please provide a valid fund\_transfer\_network | 400 | | 20425 | Please provide a valid payout\_type | 400 | | 20427 | Please provide a valid local\_payment\_network | 400 | | 20428 | Please provide a valid wallet | 400 | | 20429 | Please provide a valid swift | 400 | | 20430 | Please provide a valid local | 400 | | 20521 | For type tazapay\_account, destination\_currency should be same as payout\_currency | 400 | | 20523 | The destination currency should only be CNH for CNH payout\_currency and payout\_type should be local | 400 | | 20524 | Fund transfer network does not support remittance preference | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ----- | ------------------------------------------ | ----------- | | 2051 | Metadata config not found for the account | 400 | | 2052 | Risk config not found for the account | 400 | | 2053 | Config not supported for this account type | 500 | | 2062 | Account ID is missing or invalid | 400 | | 4000 | Invalid from currency provided | 400 | | 4001 | Invalid to currency provided | 400 | | 4004 | Invalid FX config provided | 400 | | 4005 | Invalid FX type provided | 400 | | 4006 | Invalid account\_id provided | 400 | | 4007 | Invalid admin\_id provided | 400 | | 4009 | Invalid collection currency provided | 400 | | 4010 | Invalid customer country provided | 400 | | 4011 | Invalid payment method family provided | 400 | | 4012 | Invalid from\_amount provided | 400 | | 4027 | Non-fiat currency is not supported | 400 | | 4303 | Base rate not found | 404 | | 4308 | Live base rate not found | 404 | | 5090 | Invalid account\_id provided (pricing) | 400 | | 5091 | Invalid payout transfer type | 400 | | 5092 | Invalid destination currency code | 400 | | 5093 | Invalid destination amount | 400 | | 5094 | Invalid payout currency code | 400 | | 5095 | Invalid payout amount | 400 | | 5096 | Invalid payout wallet type | 400 | | 5097 | Invalid payout quote\_id | 400 | | 5098 | Invalid charge type | 400 | | 43000 | Invalid country provided | 400 | | 43001 | Invalid currency provided | 400 | | 43014 | Invalid bank transfer type provided | 400 | # Create Quote Source: https://developer.tazapay.com/api-reference/appendix/create-quote Error codes for POST /v3/fx/quote ### POST v3/fx/quote | Code | Message | HTTP Status | | ---- | -------------------------------------------------------------------------------------------------------------- | ----------- | | 4000 | invalid from currency in request body | 400 | | 4001 | invalid to currency in request body | 400 | | 4002 | invalid markup\_type in request body, should be one of apm, card or lbt\_wire | 400 | | 4006 | invalid type in request body, should be one of apm, card, lbt\_wire for markup or payout for markdown | 400 | | 4007 | invalid account id, should have 'acc\_' as prefix followed by valid xid | 400 | | 4010 | invalid currency code in request body, should be in alpha 3 format | 400 | | 4017 | invalid/no from amount in req, is required with payment\_method\_family and must be greater than or equal to 0 | 400 | | 4018 | no payment method family in req, is required with from\_amount | 400 | | 4022 | invalid amount, should be greater than 0 | 400 | | 4044 | invalid initial amount in request body, should be greater than 0 | 400 | | 4046 | invalid converted amount in request body, should be greater than 0 | 400 | | 4047 | Cannot provide both initial\_amount and converted\_amount to create quote | 400 | | 4048 | Cannot provide the same initial\_currency and final\_currency to create quote | 400 | | 4049 | invalid to\_amount or no amount is provided | 400 | | 4300 | fx markup config not found for currency code and markup\_type. Please provide valid currency and markup type | 404 | | 4313 | mark percent obtained for currency pair is greater than or equal to 100 | 400 | # Create Refund Source: https://developer.tazapay.com/api-reference/appendix/create-refund Error codes for POST /v3/refund ### POST v3/refund | Code | Message | HTTP Status | | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 30000 | Invalid payin\_id, should have prefix 'chk\_' or 'esc\_' and should be followed by valid xid | 400 | | 30001 | Invalid payment\_attempt\_id, should have prefix 'pat\_' and should be followed by valid xid | 400 | | 30002 | Field must have a value greater than 0 | 400 | | 30004 | Please provide a valid source | 400 | | 30005 | Please provide a valid webhook URL | 400 | | 30006 | Field payment\_attempt\_id is missing, please provide a valid id with prefix 'pat\_' and should be followed by valid xid | 400 | | 30007 | Request params are missing, please provide either 'payin' or 'payment\_attempt' | 400 | | 30008 | Can not initiate refunds for payin which has multiple payment attempts | 400 | | 30009 | Can not initiate refund for unsuccessful payment attempt, refund can be requested only on succeeded payment attempts. | 409 | | 30010 | Refund is already completed for the requested payment attempt | 400 | | 30011 | Refunds cannot be initiated for this payment attempt. Reach out to [support@tazapay.com](mailto:support@tazapay.com) for further assistance with refunds. | 400 | | 30012 | The requested refund amount exceeds the total paid amount of the payment attempt, taking into account any previous refunds. | 400 | | 30014 | Refund can't be processed as the buyer phone number isn't present. | 400 | | 30015 | Invalid refund reason, please provide a valid reason | 400 | | 30016 | Collect object can not be refunded. Reach out to [support@tazapay.com](mailto:support@tazapay.com) for further assistance with refunds. | 400 | | 30017 | Your account is currently not authorized to initiate refunds. Reach out to [support@tazapay.com](mailto:support@tazapay.com) for further assistance with refunds. | 400 | | 30019 | Please provide customer details with email, customer details are required for refund processing. | 400 | | 30020 | Your account is currently not authorized to initiate refunds for this payment method. Reach out to [support@tazapay.com](mailto:support@tazapay.com) for further assistance with refunds. | 400 | | 30021 | Partial refund not supported for this payment method. Please provide full amount or reach out to [support@tazapay.com](mailto:support@tazapay.com) for further assistance with refunds. | 400 | | 30022 | Requested refund amount is below the minimum limit for this payment method. | 400 | | 30027 | Refunds are not allowed for transactions older than the allowed period for this payment method. | 400 | | 31001 | User is not authorized to perform this action | 403 | | 31003 | You are not allowed to perform this action since your account is in Dormant status. | 400 | | 31004 | You are not allowed to perform this action since your account is in Terminated status. | 400 | # Decimal Currencies Source: https://developer.tazapay.com/api-reference/appendix/decimal-currencies ### Fiat **Minor Unit:** The minor unit of a currency refers to the number of digits after the decimal separator that the currency can have. All the currencies have distinct minor units, either 0, 2, 3 or 4. The entire list can be accessed [here](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xls). The `amount` key for will always accept the denomination value with 2 decimal places in an integer format. **Example:** Consider three currencies, a 3 decimal currency KWD, a 2 decimal currency INR and a 0 decimal currency JPY. * For INR, if you want the amount to be 100.89, you pass 10089 as the value for the amount key. * For JPY, if you want the amount to be 100, you pass 10000. The last 2 digits will always be considered as 0 even if the values are different than 0. * For KWD, if you want the amount to be 100.899, you can pass 10089 as the value for the amount key. Tazapay’s system will not accept the third decimal place of 3 digit currencies. If you pass 100899, it will be considered as KWD 1008.990. ### Cryptocurrencies / Stablecoins * For stablecoin currencies, `USDT` and `USDC`, the `amount` key for will always accept the denomination value with 2 decimal places in an integer format. * For supported crypto currencies, `BTC` and `ETH`, the `amount` key for will always accept the denomination value with 8 decimal places in an integer format. # Expire Checkout Source: https://developer.tazapay.com/api-reference/appendix/expire-checkout Error codes for POST /v3/checkout/{id}/expire ### POST v3/checkout/\{id}/expire | Code | Message | HTTP Status | | ----- | -------------------------------------------------------------------------------- | ----------- | | 15500 | Checkout ID field is required and must be a valid ID, Example: chk\_id | 400 | | 15500 | Checkout ID field is required and must be a valid ID, Example: chk\_id | 404 | | 19020 | Either payment status is not in a valid state or payment link is already expired | 409 | # Fetch Adjustments Source: https://developer.tazapay.com/api-reference/appendix/fetch-adjustments Error codes for GET /v3/settlement/{id}/adjustment ### GET v3/settlement/\{id}/adjustment | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------- | ----------- | | 20070 | Field is required and must be valid xid type with prefix 'st\_' | 400 | | 20341 | Please provide a valid starting\_after | 400 | | 20342 | Please provide a valid ending\_before | 400 | | 20343 | Please provide a valid limit | 400 | # Fetch Balance Source: https://developer.tazapay.com/api-reference/appendix/fetch-balance Error codes for GET /v3/balance ### GET v3/balance | Code | Message | HTTP Status | | ----- | -------------------------------------------------------------------------- | ----------- | | 40000 | Field is required and must be valid xid type with prefix 'acc\_' | 400 | | 40007 | Field is required and must be one of mp\_dashboard, ops\_dashboard or api. | 400 | | 40015 | Primary currency cannot be a non-fiat currency | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | ------------------------------------ | ----------- | | 4000 | Invalid from currency provided | 400 | | 4001 | Invalid to currency provided | 400 | | 4004 | Invalid FX config provided | 400 | | 4005 | Invalid FX type provided | 400 | | 4006 | Invalid account\_id provided | 400 | | 4009 | Invalid collection currency provided | 400 | | 4010 | Invalid customer country provided | 400 | | 4303 | Base rate not found | 404 | | 4308 | Live base rate not found | 404 | # Fetch Balance Transaction Source: https://developer.tazapay.com/api-reference/appendix/fetch-balance-transaction Error codes for GET /v3/balance_transaction/{id} ### GET v3/balance\_transaction/\{id} | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------------- | ----------- | | 40004 | Field is required and must be valid xid type with prefix 'btr\_' | 400 | | 40006 | Access denied: You do not have the necessary permissions to access this resource. | 403 | | 40008 | Field is required and must be one of api or grpc. | 400 | # Fetch Beneficiary Source: https://developer.tazapay.com/api-reference/appendix/fetch-beneficiary Error codes for GET /v3/beneficiary/{id} ### GET v3/beneficiary/\{id} | Code | Message | HTTP Status | | ----- | ------------------------------------------------------------------------- | ----------- | | 20161 | Field is required and must be a valid beneficiary id. Example: bnf\_xid | 400 | | 20180 | Beneficiary might not exist or it is invalid, please verify and try again | 404 | | 20193 | You do not have permission to access this resource | 403 | # Fetch Collect Source: https://developer.tazapay.com/api-reference/appendix/fetch-collect Error codes for GET /v3/collect/{id} ### GET v3/collect/\{id} | Code | Message | HTTP Status | | ----- | ------------------------------------------------------------------------- | ----------- | | 19657 | Field is required and must be valid a collect id | 400 | | 19659 | The collect might not exist or it is invalid, please verify and try again | 404 | # Fetch Collects Source: https://developer.tazapay.com/api-reference/appendix/fetch-collects Error codes for GET /v3/settlement/{id}/transactions/collect ### GET v3/settlement/\{id}/transactions/collect | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------- | ----------- | | 20070 | Field is required and must be valid xid type with prefix 'st\_' | 400 | | 20340 | Please provide a valid transaction type | 400 | | 20341 | Please provide a valid starting\_after | 400 | | 20342 | Please provide a valid ending\_before | 400 | | 20343 | Please provide a valid limit | 400 | | 20344 | Please provide a valid starting\_after or ending\_before for the given type | 400 | # Fetch Entity Source: https://developer.tazapay.com/api-reference/appendix/fetch-entity Error codes for GET /v3/entity/{id} ### GET v3/entity/\{id} | Code | Message | HTTP Status | | ---- | ---------------------------------------------------------------------------------------------------------- | ----------- | | 3025 | KYB application not found | 404 | | 3036 | We regret to inform you that you currently do not have the necessary authorization to access this resource | 403 | | 3037 | Invalid entity, should have prefix 'ent\_' and should be followed by valid xid | 400 | # Fetch Exchange Rates Source: https://developer.tazapay.com/api-reference/appendix/fetch-exchange-rates Error codes for GET /v3/fx/payout ### GET v3/fx/payout | Code | Message | HTTP Status | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | 1091 | Invalid country provided in request. Please provide a valid alpha 2 country code. | 400 | | 1092 | Invalid currency provided in request. Please provide a valid alpha 3 currency code. | 400 | | 1093 | Invalid payout\_type provided in request. Should be one of local or swift. Please provide a valid payout\_type. | 400 | | 1094 | Invalid entity\_id provided in request. Should have 'ent\_' as prefix followed by valid xid. Please provide a valid entity\_id. | 400 | | 1095 | Invalid source provided in request. Should be one of dashboard, api or grpc. Please provide a valid source. | 400 | | 1098 | Payout methods not found for provided request data. Please contact [support@tazapay.com](mailto:support@tazapay.com) for more information. | 404 | # Fetch External Account Details Source: https://developer.tazapay.com/api-reference/appendix/fetch-external-account-details Error codes for GET /v3/metadata/external_account_details ### GET v3/metadata/external\_account\_details | Code | Message | HTTP Status | | ---- | --------------------------------------------------------------------------- | ----------- | | 1000 | country %s is not supported at this moment | 400 | | 1086 | Field tax\_id is required, please provide a valid tax\_id | 400 | | 1097 | Invalid bank account number. Please check the account number and try again. | 404 | | 1099 | Invalid or missing parameter. Please provide valid parameters. | 400 | # Fetch Lightning Invoice Source: https://developer.tazapay.com/api-reference/appendix/fetch-lightning-invoice Error codes for GET /v3/lightning_invoice_bolt11/{id} ### GET v3/lightning\_invoice\_bolt11/\{id} | Code | Message | HTTP Status | | ----- | ------------------------------------------------ | ----------- | | 20471 | Field is required and must be a valid invoice id | 400 | # Fetch Payin Source: https://developer.tazapay.com/api-reference/appendix/fetch-payin Error codes for GET /v3/payin/{id} ### GET v3/payin/\{id} | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------------------------------------------------- | ----------- | | 15526 | Payin Id is required. Please check whether id provided is in correct format. Example: pay\_id | 400 | | 15550 | Payin Id is required. Please check whether id provided is in correct format. Example: chk\_id/esc\_id/pay\_id/col\_id | 404 | # Fetch Payins Source: https://developer.tazapay.com/api-reference/appendix/fetch-payins Error codes for GET /v3/settlement/{id}/transactions/payin ### GET v3/settlement/\{id}/transactions/payin | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------- | ----------- | | 20070 | Field is required and must be valid xid type with prefix 'st\_' | 400 | | 20340 | Please provide a valid transaction type | 400 | | 20341 | Please provide a valid starting\_after | 400 | | 20342 | Please provide a valid ending\_before | 400 | | 20343 | Please provide a valid limit | 400 | | 20344 | Please provide a valid starting\_after or ending\_before for the given type | 400 | # Fetch Payment Attempt Source: https://developer.tazapay.com/api-reference/appendix/fetch-payment-attempt Error codes for GET /v3/payment_attempt/{id} ### GET v3/payment\_attempt/\{id} | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------------------------------------------------- | ----------- | | 15550 | Payin Id is required. Please check whether id provided is in correct format. Example: chk\_id/esc\_id/pay\_id/col\_id | 400 | | 19100 | Invalid payment\_attempt\_id, should have prefix 'pat\_' and should be followed by valid xid | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | -------------------------- | ----------- | | 4008 | Invalid quote\_id provided | 400 | | 4304 | FX quote not found | 404 | # Fetch Payout Source: https://developer.tazapay.com/api-reference/appendix/fetch-payout Error codes for GET /v3/payout/{id} ### GET v3/payout/\{id} | Code | Message | HTTP Status | | ----- | -------------------------------------------------------------------- | ----------- | | 20195 | Field is required and must be a valid payout\_id | 400 | | 20180 | Payout might not exist or it is invalid, please verify and try again | 404 | | 20193 | You do not have permission to access this resource | 403 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | -------------------------- | ----------- | | 4008 | Invalid quote\_id provided | 400 | | 4304 | FX quote not found | 404 | # Fetch Payouts Source: https://developer.tazapay.com/api-reference/appendix/fetch-payouts Error codes for GET /v3/settlement/{id}/transactions/payout ### GET v3/settlement/\{id}/transactions/payout | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------- | ----------- | | 20070 | Field is required and must be valid xid type with prefix 'st\_' | 400 | | 20340 | Please provide a valid transaction type | 400 | | 20341 | Please provide a valid starting\_after | 400 | | 20342 | Please provide a valid ending\_before | 400 | | 20343 | Please provide a valid limit | 400 | | 20344 | Please provide a valid starting\_after or ending\_before for the given type | 400 | # Fetch Quote Source: https://developer.tazapay.com/api-reference/appendix/fetch-quote Error codes for GET /v3/fx/quote/{id} ### GET v3/fx/quote/\{id} | Code | Message | HTTP Status | | ---- | --------------------------------------------------------------------- | ----------- | | 4009 | invalid quote\_id, should have 'fx\_' as prefix followed by valid xid | 400 | | 4310 | Record not found for the provided quote\_id | 404 | # Fetch Refund Source: https://developer.tazapay.com/api-reference/appendix/fetch-refund Error codes for GET /v3/refund/{id} ### GET v3/refund/\{id} | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------------------------------- | ----------- | | 30050 | Invalid refund\_id, should have prefix 'rfd\_' and should be followed by valid xid | 400 | | 31001 | User is not authorized to perform this action | 403 | # Fetch Refunds Source: https://developer.tazapay.com/api-reference/appendix/fetch-refunds Error codes for GET /v3/settlement/{id}/transactions/refund ### GET v3/settlement/\{id}/transactions/refund | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------- | ----------- | | 20070 | Field is required and must be valid xid type with prefix 'st\_' | 400 | | 20340 | Please provide a valid transaction type | 400 | | 20341 | Please provide a valid starting\_after | 400 | | 20342 | Please provide a valid ending\_before | 400 | | 20343 | Please provide a valid limit | 400 | | 20344 | Please provide a valid starting\_after or ending\_before for the given type | 400 | # Fund Payout Source: https://developer.tazapay.com/api-reference/appendix/fund-payout Error codes for POST /v3/payout/{id}/fund ### POST v3/payout/\{id}/fund | Code | Message | HTTP Status | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 20290 | Field is required and must be a valid payout\_id | 400 | | 20291 | Field value must be either one of validate/confirm | 400 | | 20182 | Payout status cannot be changed for the current status | 400 | | 20193 | You do not have permission to access this resource | 403 | | 20199 | There is insufficient balance in your account to make the desired payout. Please ensure you have added sufficient funds to your account before retrying. | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | -------------------------- | ----------- | | 4008 | Invalid quote\_id provided | 400 | | 4304 | FX quote not found | 404 | # Generic Error Codes Source: https://developer.tazapay.com/api-reference/appendix/generic Error codes that may occur across all Tazapay APIs Generic error codes are returned by all Tazapay API endpoints regardless of the resource being accessed. These errors relate to authentication, request formatting, rate limiting, and infrastructure-level issues. ## Generic Error Codes | Code | Message | HTTP Status | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | 100 | Failure on decoding the json request. The format for Json is not correct, please check the syntax & case sensitivity for any missing brackets, semi-colons, capitalizations, or any other formatting errors. | 400 | | 101 | Something went wrong with this API | 500 | | 102 | Something went wrong with this API | 500 | | 103 | Invalid parameter in the URL path. Example : /xyz/my\_value/abc — my\_value is invalid | 400 | | 104 | Invalid parameter in the URL path. Example : /xyz?sort=my\_value — my\_value is invalid | 400 | | 105 | The resource you are trying to retrieve is not present. This error occurs when trying to Get or Read a data point (e.g. transaction, user, KYB) that does not exist. | 404 | | 106 | Invalid access token. Please check your authentication flow and try again. | 401 | | 107 | Access token has expired. Please generate a new token to continue. | 401 | | 108 | Invalid basic auth. Please check your authentication flow and try again. | 401 | | 109 | Empty basic auth. Please check your authentication flow and try again. | 401 | | 110 | Too Many Requests: Exceeded the allowable rate of requests. Please wait and try again later. | 429 | | 111 | Invalid api key. Please check your authentication flow and try again. | 401 | | 112 | Unsupported file type. Please check the file type and try again. | 400 | *** ## HTTP Status Code Reference The following HTTP status codes may be returned by any API endpoint: | HTTP Status | Meaning | When It Occurs | | ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------- | | 200 | OK | Request succeeded | | 201 | Created | Resource successfully created | | 400 | Bad Request | Invalid request parameters or body — check the `errors` array for specifics | | 401 | Unauthorized | Missing, expired, or invalid authentication credentials (API key, access token, or basic auth) | | 403 | Forbidden | Valid credentials but insufficient permissions to access the resource | | 404 | Not Found | The requested resource does not exist | | 405 | Method Not Allowed | The HTTP method used is not supported for this endpoint | | 409 | Conflict | The request conflicts with the current state of the resource (e.g. duplicate action, invalid status transition) | | 429 | Too Many Requests | Rate limit exceeded — wait before retrying | | 500 | Internal Server Error | An unexpected server-side error occurred — contact support if this persists | | 503 | Service Unavailable | The server is temporarily unable to handle the request — retry after a delay | | 504 | Gateway Timeout | An upstream service did not respond in time — retry the request | # Get Checkout Session Source: https://developer.tazapay.com/api-reference/appendix/get-checkout Error codes for GET /v3/checkout/{id} ### GET v3/checkout/\{id} | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------------------- | ----------- | | 15500 | Checkout ID field is required and must be a valid ID, Example: chk\_id | 400 | | 15500 | Checkout ID field is required and must be a valid ID, Example: chk\_id | 404 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | -------------------------- | ----------- | | 4008 | Invalid quote\_id provided | 400 | | 4304 | FX quote not found | 404 | # Get Customer Source: https://developer.tazapay.com/api-reference/appendix/get-customer Error codes for GET /v3/customer/{id} ### GET v3/customer/\{id} | Code | Message | HTTP Status | | ---- | ---------------------- | ----------- | | 2306 | Search text is missing | 400 | | 2307 | Account id is missing | 400 | | 2308 | Account id is missing | 400 | # IBAN Checksum Validation Source: https://developer.tazapay.com/api-reference/appendix/iban-checksum-validation The International Bank Account Number (IBAN) uses the **Mod-97-10 checksum algorithm** to validate check digits and ensure data integrity. ## Mod-97-10 Algorithm The algorithm validates that the IBAN check digits produce a remainder of **1** when calculated. ### Validation Steps **Step 1**: Move the first 4 characters to the end ``` GB29NWBK60161331926819 → NWBK60161331926819GB29 ``` **Step 2**: Replace letters with numbers (A=10, B=11, ..., Z=35) ``` N=23, W=32, B=11, K=20, G=16, B=11 NWBK60161331926819GB29 → 233211102060161331926819161129 ``` **Step 3**: Calculate modulo 97 ``` 233211102060161331926819161129 mod 97 = 1 ``` **Step 4**: Validate * **If remainder = 1**: IBAN is valid ✓ * **If remainder ≠ 1**: IBAN is invalid ✗ ## Implementation in Go ```go theme={null} package main import ( "fmt" "strconv" "strings" ) func ValidateIBAN(iban string) bool { // Remove spaces and convert to uppercase iban = strings.ToUpper(strings.ReplaceAll(iban, " ", "")) // Check length if len(iban) < 15 || len(iban) > 34 { return false } // Step 1: Move first 4 chars to end rearranged := iban[4:] + iban[:4] // Step 2: Convert letters to numbers (A=10, B=11, ..., Z=35) numericIBAN := "" for _, char := range rearranged { if char >= 'A' && char <= 'Z' { numericIBAN += strconv.Itoa(int(char-'A') + 10) } else { numericIBAN += string(char) } } // Step 3: Calculate mod 97 efficiently (avoids big.Int) remainder := 0 for _, digit := range numericIBAN { remainder = (remainder*10 + int(digit-'0')) % 97 } // Step 4: Valid if remainder equals 1 return remainder == 1 } func main() { testCases := []struct { iban string valid bool }{ {"GB29NWBK60161331926819", true}, {"DE89370400440532013000", true}, {"GB00INVALID00000000000", false}, } for _, tc := range testCases { result := ValidateIBAN(tc.iban) status := "✓" if !result { status = "✗" } fmt.Printf("%s %s (expected: %v)\n", status, tc.iban, tc.valid) } } ``` ## Related Resources * [Create Beneficiary API](/api-reference/tazapay-api/create-beneficiary) * [Create Payout API](/api-reference/tazapay-api/create-payout) * [Field Validation Updates](/changelog/2026/field-validation-updates) # List Balance Transactions Source: https://developer.tazapay.com/api-reference/appendix/list-balance-transactions Error codes for GET /v3/balance_transaction ### GET v3/balance\_transaction | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------------------- | ----------- | | 40016 | limit is invalid and should be between 1 to 100 | 400 | | 40017 | created object should not contain all or gt and gte or lt and lte at the same time | 400 | | 40018 | Invalid value provided for starting\_after and should be a valid balance transaction id | 400 | | 40019 | Invalid value provided for ending\_before and should be a valid balance transaction id | 400 | # List Entity Source: https://developer.tazapay.com/api-reference/appendix/list-entity Error codes for GET /v3/entity ### GET v3/entity | Code | Message | HTTP Status | | ---- | ---------------------------------------------------------------------------------------------------------- | ----------- | | 3036 | We regret to inform you that you currently do not have the necessary authorization to access this resource | 403 | # Payout Failure Reason Codes (Deprecating Soon) Source: https://developer.tazapay.com/api-reference/appendix/payout-failure-reasons The status_description field of the payout object will be populated with the error code when a payout transitions to the failed state. | Error Code | Error Message | Description | | ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | PO1001 | insufficient\_balance | There is insufficient balance in your account to make the desired payout | | PO1002 | invalid\_destination | This occurs when a banking channel tells us that an account is invalid. Typically, this means that the account is not yet registered at the destination bank or the bank has blocked the account. This also occurs for newly created bank accounts which have yet to be updated to national databases. | | PO1003 | rejected\_by\_bank | The destination bank can reject the incoming funds for a variety of reasons. The reasons are typically to do with compliance or the destination account's ability to receive funds | | PO1004 | rejected\_by\_channel | The switching network can reject funds transfer for a variety of reasons. The reasons are typically to do with compliance or the destination account's ability to receive funds | | PO1005 | cancelled | The payout has been cancelled by the sender | | PO1006 | payout\_expired | The payout was not funded within the required time limit and has expired. | | PO1007 | exchange\_rate\_expired | The updated exchange\_rate is rejected | | PO1008 | entity\_approval\_rejected | The entity approval is rejected | | PO1000 | other | The reason of failure cannot be specified | | PO1009 | payout\_expired | The payout was not approved within the required time limit and has expired. | | PO1010 | incomplete\_details | The payout could not be processed because the provided details are incomplete. Ensure that all required fields, such as account number, bank name, and beneficiary details are correctly filled in. | | PO1011 | incorrect\_tax\_id | The payout could not be completed due to an incorrect or invalid tax identification number. | | PO1012 | incorrect\_swift\_code | The SWIFT code provided for the payout is incorrect or invalid | | PO1013 | incorrect\_beneficiary\_name | The beneficiary name provided does not match the records at the receiving bank. | | PO1014 | invalid\_account\_number | The account number provided is invalid or does not exist | | PO1015 | compliance\_issue | The payout has been flagged for a compliance issue. This may occur if the transaction violates regulatory guidelines or Tazapay's policies. | | PO5001 | transaction\_failed | Transaction failed at the bank's end, please retry after some time. | | PO5002 | transaction\_timedout | Transaction timed out, please retry. | | PO5506 | invalid\_account | Beneficiary details are invalid. | | PO5512 | rejected\_by\_beneficiary\_bank | Rejected by beneficiary bank | | PO5513 | returned\_from\_beneficiary | Transaction was rejected by the beneficiary bank | | PO5519 | invalid\_transaction | The transaction is invalid. | | PO5522 | declined\_by\_bank | Transaction has been declined by the bank, please retry after some time or verify bank details. | | PO5524 | invalid\_ifsc\_code | IFSC code is incorrect. Please amend and retry. | | PO5530 | transaction\_not\_allowed | Transaction declined as the beneficiary account is not allowed to receive credits as per guideline. | | PO5532 | foreign\_inward\_remittance\_not\_allowed | Transaction has been declined by beneficiary's bank. | | PO5535 | invalid\_document\_id | Transaction declined due to invalid beneficiary document ID. | | PO5541 | invalid\_originating\_bank\_bic | There was an error processing your transaction. Please try again shortly. If the issue continues, kindly send a screenshot of this error to [error@tazapay.com](mailto:error@tazapay.com) for further assistance. | | PO5545 | intermediary\_bic\_ is\_incorrect | There was an error processing your transaction. Please try again shortly. If the issue continues, kindly write to [support@tazapay.com](mailto:support@tazapay.com) for further assistance. | | PO5546 | swift\_bic\_of\_payer/payee\_is\_incorrect | There was an error processing your transaction. Please try again shortly. If the issue continues, kindly write to [support@tazapay.com](mailto:support@tazapay.com) for further assistance. | | PO6255 | blacklisted\_remitter\_or\_beneficiary | Remitter or beneficiary found in the negative list. | | PO6256 | blacklisted\_beneficiary | Beneficiary name has been found in the blacklisted list. | | PO6257 | blacklisted\_remitter\_and\_beneficiary | Remitter and beneficiary found in the negative list. | | PO6258 | beneficiary\_keyword\_contains\_companyname | The beneficiary name contains keywords usually found in company names, while it was indicated that the beneficiary is an individual. Please correct and retry. | | PO6259 | beneficiary\_keyword\_not\_allowed | The beneficiary name contains keywords usually found in institutions that are not allowed to receive funds via this route. This transaction cannot proceed. | | PO6260 | remitter\_keyword\_not\_allowed | The remitter name contains keywords usually found in institutions that are not allowed to receive funds via this route. This transaction cannot proceed. | | PO6261 | transaction\_on\_hold | The transaction is on hold due to AML check. | | PO6262 | suspected\_fraud | Transaction declined due to suspected fraud. | | PO6263 | declined\_by\_antifraud\_or\_compliance | Transaction declined due to suspected fraud. | | PO6264 | divergence\_tax\_id\_information | Transaction declined due to divergence in tax id information | | PO5559 | invalid\_wallet\_address | Transaction declined due to invalid wallet address information | | PO5561 | invalid\_ln\_invoice | Transaction declined due to invalid or malformed Lightning Network invoice. | | PO5562 | invoice\_expired | Transaction declined as the Lightning Network invoice has expired or has less than 10 minutes remaining. | | PO5563 | invoice\_amount\_mismatch | Transaction declined as the Lightning Network invoice amount does not match the payout amount. | | PO5564 | invoice\_already\_paid | Transaction declined as the Lightning Network invoice has already been paid. | # Payout Failure Reason Codes Source: https://developer.tazapay.com/api-reference/appendix/payout-failure-reasons-updated The failure.code field of the payout object will be populated with the error code when a payout transitions to the failed state. The Payout object has been enhanced to include a new `failure` object in the response. This provides more structured and cleaner failure information when a payout has failed, making it easier to programmatically identify and handle failure scenarios. We will be deprecating the [old failure codes](/api-reference/appendix/payout-failure-reasons) that were populated in the `status_description` field soon. It is recommended to consume these failure codes instead. | Error Code | Category | Description / Message | | :--------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | | PF000000 | General Failures | Generic fallback, the reason of failure cannot be specified | | PF000100 | General Failures | Payout cancelled on remitter's request | | PF000200 | General Failures | The fund transfer network is facing a temporary downtime | | PF010000 | Funding / Expiry | Generic payout funding or approval failure | | PF010100 | Funding / Expiry | The payout was not funded within the required time limit. | | PF010200 | Funding / Expiry | The payout was not approved within the required time limit. | | PF010300 | Funding / Expiry | The approver rejected the revised exchange rate; the exchange rate for the payout was updated after creation | | PF020000 | Beneficiary / Bank Details Invalid or Incomplete | A generic error occurred during beneficiary details validation. | | PF020100 | Beneficiary / Bank Details Invalid or Incomplete | The destination details (bank account details/wallet address/proxy id) are invalid, malformed, or not recognized by the bank/network. | | PF020101 | Beneficiary / Bank Details Invalid or Incomplete | Bank identification code is missing/invalid | | PF020102 | Beneficiary / Bank Details Invalid or Incomplete | Tax identification number is missing/invalid | | PF020103 | Beneficiary / Bank Details Invalid or Incomplete | Beneficiary name is missing/invalid | | PF020104 | Beneficiary / Bank Details Invalid or Incomplete | Missing/invalid deposit key (For example - upi handle or pix key) | | PF020105 | Beneficiary / Bank Details Invalid or Incomplete | Missing/invalid wallet deposit address | | PF020106 | Beneficiary / Bank Details Invalid or Incomplete | Bank account number is missing/invalid | | PF020107 | Beneficiary / Bank Details Invalid or Incomplete | Bank branch is missing/invalid | | PF020108 | Beneficiary / Bank Details Invalid or Incomplete | Bank name is missing/invalid | | PF020109 | Beneficiary / Bank Details Invalid or Incomplete | IBAN is missing/invalid. | | PF020200 | Beneficiary / Bank Details Invalid or Incomplete | The destination details do not match the beneficiary's registered information (e.g., beneficiary name mismatch). | | PF020201 | Beneficiary / Bank Details Invalid or Incomplete | The beneficiary name does not match the beneficiary's registered name. | | PF020202 | Beneficiary / Bank Details Invalid or Incomplete | The beneficiary tax id does not match the beneficiary's registered tax id. | | PF020203 | Beneficiary / Bank Details Invalid or Incomplete | The beneficiary receiving currency does not match the bank account currency. | | PF020300 | Beneficiary / Bank Details Invalid or Incomplete | The receiving bank is not supported | | PF020400 | Beneficiary / Bank Details Invalid or Incomplete | The specified account type is missing or not supported. | | PF020500 | Beneficiary / Bank Details Invalid or Incomplete | Destination account is blocked/closed or not supported | | PF020600 | Beneficiary / Bank Details Invalid or Incomplete | Beneficiary address is invalid | | PF030000 | Bank / Network Failure or Rejections | A general error occurred due to beneficiary bank or network rejection/failure | | PF030100 | Bank / Network Failure or Rejections | Beneficiary bank rejected incoming funds | | PF030101 | Bank / Network Failure or Rejections | Beneficiary bank rejected incoming funds as foreign inward remittance is not allowed. | | PF030102 | Bank / Network Failure or Rejections | Beneficiary bank rejected incoming funds as payout amount is above the allowed amount for account type. | | PF030103 | Bank / Network Failure or Rejections | Beneficiary bank rejected incoming funds as the bank/account does not allow the indicated payout transfer type | | PF030104 | Bank / Network Failure or Rejections | Beneficiary bank does not support the fund transfer network | | PF030200 | Bank / Network Failure or Rejections | Fund transfer network rejected transfer of funds | | PF030300 | Bank / Network Failure or Rejections | Funds were returned by the beneficiary bank | | PF030400 | Bank / Network Failure or Rejections | Transaction failed due to beneficiary bank technical issue | | PF030500 | Bank / Network Failure or Rejections | Transaction failed due to beneficiary bank cut off limit | | PF040000 | Compliance / AML / Fraud / Risk Controls | Payout is flagged for compliance/Fraud/AML risks; may violate regulations or Tazapay policies. | | PF040100 | Compliance / AML / Fraud / Risk Controls | Remitter/Beneficiary failed compliance check (individual/business is blocked/ineligible to make/receive payments) | | PF040101 | Compliance / AML / Fraud / Risk Controls | Remitter failed compliance check (individual/business is blocked/ineligible to make payments) | | PF040102 | Compliance / AML / Fraud / Risk Controls | Beneficiary failed compliance check (individual/business is blocked/ineligible to receive payments) | | PF040103 | Compliance / AML / Fraud / Risk Controls | Beneficiary name does not align with the beneficiary type. | | PF040104 | Compliance / AML / Fraud / Risk Controls | Remitter name does not align with the remitter type. | | PF040105 | Compliance / AML / Fraud / Risk Controls | Beneficiary details consists of restricted keywords | | PF040106 | Compliance / AML / Fraud / Risk Controls | Remitter details consists of restricted keywords | | PF040200 | Compliance / AML / Fraud / Risk Controls | The payout was created on behalf of an entity that has been rejected | | PF060000 | RFI | A general error occurred while reviewing RFI data, preventing payout approval. | | PF060100 | RFI | Submitted RFI documents were missing required fields, improperly formatted, or failed validation checks. | | PF060200 | RFI | The submitted RFI data contained inconsistencies or conflicts with previously provided information. | | PF060300 | RFI | One or more uploaded documents were expired or no longer valid at the time of review. | | PF060400 | RFI | The payment was rejected after manual compliance review of the RFI submission. | | PF060500 | RFI | Unable to continue with the payment due to an existing RFI on the remitter data. | | PF060600 | RFI | The RFI response or review was not completed within the required time window. | | PF070000 | Remitter Details Invalid or Incomplete | A generic error occurred during remitter details validation. | | PF070100 | Remitter Details Invalid or Incomplete | Remitter address is missing/invalid. | | PF070200 | Remitter Details Invalid or Incomplete | Fund transfer network is not enabled for remitter | # Payout Metadata Source: https://developer.tazapay.com/api-reference/appendix/payout-metadata Error codes for POST /v3/metadata/payout/bank ### POST v3/metadata/payout/bank | Code | Message | HTTP Status | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | 1040 | Account Id is required. Please check whether id provided is in correct format. Example: acc\_ | 400 | | 1091 | Invalid country provided in request. Please provide a valid alpha 2 country code. | 400 | | 1092 | Invalid currency provided in request. Please provide a valid alpha 3 currency code. | 400 | | 1093 | Invalid payout\_type provided in request. Should be one of local or swift. Please provide a valid payout\_type. | 400 | | 1094 | Invalid entity\_id provided in request. Should have 'ent\_' as prefix followed by valid xid. Please provide a valid entity\_id. | 400 | | 1095 | Invalid source provided in request. Should be one of dashboard api or grpc. Please provide a valid source. | 400 | | 1096 | Payout creation failed for provided country. Please contact [support@tazapay.com](mailto:support@tazapay.com) for more information. | 500 | | 1097 | Payout methods not found for provided request data. Please contact [support@tazapay.com](mailto:support@tazapay.com) for more information. | 404 | | 1098 | Invalid bank account number. Please check the account number and try again. | 404 | | 1099 | Invalid or missing parameter. Please provide valid parameters. | 400 | | 1086 | Field tax\_id is required please provide a valid tax\_id | 400 | | 1049 | Document reference is invalid. Please provide valid document reference. | 400 | | 1050 | Document type is missing. Please provide valid document type. | 400 | | 1051 | Invalid URL format. Please make sure to provide a valid URL. | 400 | | 1052 | Document name is missing. Please provide valid document name. | 400 | | 1053 | URL you have provided could not be reached | 404 | | 1054 | URL you have provided does not have a downloadable document available | 404 | | 1000 | country %s is not supported at this moment | 404 | | 1011 | given currency %s is not supported | 404 | | 1100 | Invalid fund\_transfer\_network provided. The specified fund transfer network is not supported for this country and currency combination. | 400 | #### Internal Service Errors | Code | Message | HTTP Status | | ---- | ------------------------------ | ----------- | | 4000 | Invalid from currency provided | 400 | | 4001 | Invalid to currency provided | 400 | | 4303 | Base rate not found | 404 | | 4308 | Live base rate not found | 404 | # Payout Reversal Reason Codes Source: https://developer.tazapay.com/api-reference/appendix/payout-reversal-reasons The status_description field of the payout object will be populated with the reason code when a payout transitions to the reversed state. | Reason Code | Category | Description | | :---------- | :------------------------ | :-------------------------------------------- | | PR1001 | Account-Related Issues | Invalid Or Closed Beneficiary Account | | PR1002 | Account-Related Issues | Incorrect Beneficiary Details | | PR1003 | Account-Related Issues | Account Not Eligible For Cross-Border Credits | | PR1004 | Account-Related Issues | Dormant Or Restricted Account | | PR2001 | Compliance Issues | Sanctions Or Screening Failure | | PR3001 | Beneficiary Action Issues | Unclaimed Or Expired Payout | | PR3002 | Beneficiary Action Issues | Beneficiary Declined Payment | | PR0001 | Other Issues | Other | # Submit Entity Source: https://developer.tazapay.com/api-reference/appendix/submit-entity Error codes for POST /v3/entity/{id}/submit ### POST v3/entity/\{id}/submit | Code | Message | HTTP Status | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 3025 | KYB application not found | 404 | | 3028 | Unable to update since the KYB is already submitted. please contact us at [ops@tazapay.com](mailto:ops@tazapay.com) if there is a change | 400 | | 3048 | The KYB application cannot be updated in its current state. please contact us at [support@tazapay.com](mailto:support@tazapay.com) if there is a change in the entity's details. | 400 | # Supported File Types For Uploads Source: https://developer.tazapay.com/api-reference/appendix/supported-file-types-for-uploads This guide outlines the file types supported by our stack. Please refer to the sections below for details on each category. Maximum file size supported is 50 MB. ### 1. Images Our stack supports the following image file formats: * **.jpg** / **.jpeg** **(Joint Photographic Experts Group):** A widely used lossy compression method suitable for photographs and complex images. * **.png** **(Portable Network Graphics):** A lossless compression format that supports transparency, making it ideal for graphics, logos, and images requiring clear backgrounds. * **.bmp** **(Bitmap):**. A raster graphics image file format used to store digital images, independent of display devices. These files are typically uncompressed or minimally compressed and can be quite large. * **.tif** / **.tiff** **(Tagged Image File Format):**. A flexible and adaptable file format often used for storing raster graphics, popular in photography, desktop publishing, and medical imaging. It can be lossless or lossy. * **.svg** **(Scalable Vector Graphics)**: An XML-based vector image format that allows for scalability without loss of quality. Ideal for logos, icons, and illustrations. * **.gif** **(Graphics Interchange Format)**: Supports animation and lossless compression, commonly used for simple animations and web graphics with limited color palettes. * **.ico** **(Icon)**: An image file format used for computer icons in Microsoft Windows. It can contain multiple images at different sizes and color depths. * **.webp**: A modern image format developed by Google that provides superior lossless and lossy compression for images on the web. ### 2. Documents Our application supports the following document file formats: * **.csv** **(Comma Separated Values)**: A plain text file that stores tabular data, where values are separated by commas. * **.pdf** **(Portable Document Format):** A file format used to present documents in a manner independent of application software, hardware, and operating systems. It can contain text, images, hyperlinks, and more. * **.doc**: A proprietary word processing document format used by older versions of Microsoft Word. * **.docx**: An XML-based document format used by newer versions of Microsoft Word. * **.odt** **(OpenDocument Text)**: An open standard document format used by word processors like LibreOffice Writer and Apache OpenOffice Writer. * **.ott** **(OpenDocument Text Template)**: A template format for OpenDocument Text documents. * **.rtf** **(Rich Text Format)**: A proprietary document file format developed by Microsoft for cross-platform document interchange. * **.txt** **(Plain Text)**: A simple file format that contains unformatted text. * **.md** **(Markdown)**: A lightweight markup language with plain text formatting syntax. Often used for creating web content, documentation, and readme files. * **.tex** **(LaTeX)**: A document preparation system widely used for typesetting technical and scientific documents. ### 3. Spreadsheets Our application supports the following spreadsheet file formats: * **.xls**: A proprietary spreadsheet file format used by older versions of Microsoft Excel. * **.xlsx**: An XML-based spreadsheet file format used by newer versions of Microsoft Excel. * **.ods** **(OpenDocument Spreadsheet)**: An open standard spreadsheet format used by spreadsheet programs like LibreOffice Calc and Apache OpenOffice Calc. * **.ots** **(OpenDocument Spreadsheet Template)**: A template format for OpenDocument Spreadsheet documents. ### 4. Presentations Our application supports the following presentation file formats: * **.ppt**: A proprietary presentation file format used by older versions of Microsoft PowerPoint. * **.pptx**: An XML-based presentation file format used by newer versions of Microsoft PowerPoint. ### 5. Compressed Archives Our application supports the following compressed archive file formats: * **.zip**: A popular archive file format that supports lossless data compression. * **.tar** **(Tape Archive)**: A common archive format that bundles multiple files into one, often used in conjunction with compression formats. * **.gz** **(Gzip)**: A file format used for data compression, typically used to compress single files. Often combined with `.tar` to create `.tar.gz` archives. * **.bz2** **(Bzip2):** Another file format used for data compression, generally offering higher compression ratios than Gzip but with slower compression speed. Often combined with `.tar` to create `.tar.bz2` archives. * **.xz**: A lossless data compression format that generally achieves higher compression ratios than both Gzip and Bzip2. Often combined with `.tar` to create `.tar.xz` archives. * **.7z** **(7-Zip)**: A high-compression archive format known for its high compression ratio and strong encryption. * **.rar** **(Roshal Archive)**: A proprietary archive file format that also supports data compression, error recovery, and file spanning. ### 6. JSON, XML, YAML Our application supports the following data serialization formats: * **.json** **(JavaScript Object Notation)**: A lightweight data-interchange format with a simple text-based structure. * **.xml** **(Extensible Markup Language)**: A markup language designed for carrying data. It is both human-readable and machine-readable. * **.yaml** **(YAML Ain't Markup Language) or (Yet Another Markup Language)**: A human-friendly data serialization standard for all programming languages. Commonly used for configuration files. * **.yml**: A common file extension for YAML files, interchangeable with `.yaml`. This guide provides a comprehensive list of the file types currently supported by our stack. We may add support for more file types in future updates. Please refer back to this guide for the latest information. # Supported Industry Verticals Source: https://developer.tazapay.com/api-reference/appendix/supported-industry-verticals This is the list of support industry verticals for businesses for Entity Creation * Digital Products - Apps, eBooks, Blogs & Games * Digital Products - Digital Merchandise * Digital Products - Music, Video, Channels & Podcast * Digital Products - Online Gaming (based on skill) * Digital Products - Other Digital Goods * Digital Products - Large Digital Goods Merchant (>25 Mn Txns annually) *** * Ecommerce - Home interior fixtures and decorating items * Ecommerce - Miscellaneous Clothing (e.g., Swimwear) * Ecommerce - Men and boys clothing * Ecommerce - Meat & Poultry * Ecommerce - Luggage and storage (incl backpacks, briefcases, purses and wallets) * Ecommerce - Home, Decor & Furniture - Warehouse Stores * Ecommerce - Home Appliances * Ecommerce - Hobby, Toy, and Game Shops * Ecommerce - Hardware stores * Ecommerce - Electrical and plumbing supplies, tools and power tools * Ecommerce - Glassware/Crystal Stores * Ecommerce - Gift, Card, Novelty and Souvenir Shops * Ecommerce - General Merchandise * Ecommerce - General clothing stores (for men, women, children) * Ecommerce - General clothing stores (for men and women) * Ecommerce - Finished Furniture and accessories * Ecommerce - Custom made clothing (to - order) * Ecommerce - Fur jackets, coats * Ecommerce - Food & Non - Alcohol Drinks (Miscellaneous / Specialty stores) * Ecommerce - Food & Non - Alcohol Drinks (Grocery and Supermarkets) * Ecommerce - Food & Non - Alcohol Drinks (Dairy products) * Ecommerce - Food & Non - Alcohol Drinks (Confectionery / Candy) * Ecommerce - Food & Non - Alcohol Drinks (Bakeries) * Ecommerce - Equipment, Tool, Furniture, and Appliance Rental and Leasing * Ecommerce - Electronic Hardware, Tools & Parts * Ecommerce - Duty Free Stores * Ecommerce - Dropshipping * Ecommerce - Drapery, Window Covering, and Upholstery Stores * Ecommerce - Diversified/Others * Ecommerce - Discount Stores * Ecommerce - Consumer Electronics (Mobiles) * Ecommerce - Consumer Electronics * Ecommerce - Clothing rental * Ecommerce - Children clothing * Ecommerce - Camera and Photographic Supply Stores * Ecommerce - Building & Construction Materials (Glass, Paint and Wallpaper) * Ecommerce - Building & Construction Materials (General) * Ecommerce - Building & Construction Materials (Floor Covering) * Ecommerce - Beauty Products & Cosmetics * Ecommerce - Automobiles (B2B) - Motor Vehicle Supplies and New Parts * Ecommerce - Automobiles - Motorcycle Shops and Dealers * Ecommerce - Automobiles - Car and Truck Dealers (Used Only) Sales, Service, Repairs, Parts, and Leasing * Ecommerce - Automobiles - Automobile sale/lease and repair, replacement of parts * Ecommerce - Automobiles - Bicycles, bicycle parts, accessories and repair * Ecommerce - Automobiles - Automobile tyre sale, installation and repair * Ecommerce - Automobiles - Automobile parts/tools, accessories and equipment * Ecommerce - Artwork / Art Dealers and Galleries * Ecommerce - Art & Craft Materials, Handicraft and tools * Ecommerce - Aroma, Organic & Herbal * Ecommerce - AgriProducts - Garden Products and Fertilizers * Ecommerce - AgriProducts - Florists and Novelty Products * Ecommerce - Supplements or Nutraceuticals * Ecommerce - Sports & Travel Goods * Ecommerce - Sports clothing * Ecommerce - Stamp and Coin Stores * Ecommerce - Used Merchandise and Secondhand Stores * Ecommerce - Sewing, Needlework, Fabric and Piece Goods Stores * Ecommerce - Religious Goods Stores * Ecommerce - Pet Food * Ecommerce - Wigs, Toupees, hair pieces and extensions * Ecommerce - Footwear including athletic footwear * Ecommerce - Women fashion * Ecommerce - Women accessories and specialty shops (e.g., handbags, scarfs, costume jewellery, etc) * Ecommerce - Books Stores * Ecommerce - Packaging, Office & Stationery * Ecommerce - Music Stores - Musical Instruments, Pianos, and Sheet Music *** * Ecommerce (B2B) - Building & Construction Materials (General) * Ecommerce (B2B) - Uniform supply and Commercial / Industrial clothing * Ecommerce (B2B) - Clocks, watches, silverware gems and jewelry, precious metals and jewelry repair * Ecommerce (B2B) - Commercial footwear * Ecommerce (B2B / Others) - Medical, dental, ophthalmic and hospital equipment and supplies & PPE * Ecommerce (B2C) - Clocks, watches, silverware gems and jewelry, precious metals and jewelry repair *** * Education - Elementary and Secondary Schools * Education - Elearning, Online Tutoring, Homework & Test Prep * Education - Colleges, Universities, Professional Schools, and Junior Colleges * Education - Online Education and Correspondence Schools * Education - Colleges, School or Universities * Education (others) - Other Educational Services not elsewhere classified * Education (others) - Business and Secretarial Schools * Education (others) - Vocational and Trade Schools *** * Financial Service - Life and Non - Life Insurance policies * Financial Service - Investment Banking & Financial Advisory * Financial Service - Other Financial Services (Automated Cash disbursements) * Financial Service - Other Financial Services (Manual Cash disbursements) * Financial Service - Other Financial Services (Non - classified) * Financial Service - Remittance & MSB * Financial Service - CFD and Forex * Financial Service - Banks and NBFI * Financial Service - Brokerages & Exchanges * Financial Service - Carbon Credit * Financial Service - Crowdfunding platform (equity) * Financial Service - Crowdfunding platforms (debt) * Financial Service - Digital Wallets, PSPs & Fintech * Financial Service - Fund, Wealth Management & Investment Holding * Financial Service - Prop Trading Simulation * Financial Services - Intra - Company Purchases *** * General Industries - Trade & Wholesale of General Goods * General Industries - Trade & Wholesale of General Goods (Commercial Equipment (Not Elsewhere Classified)) * General Industries - Trade & Wholesale of General Goods (Chemicals and Allied Products (Not Elsewhere Classified)) * General Industries - Trade & Wholesale of General Goods (Computers Hardware, Software and Related equipment) * General Industries - Trade & Wholesale of General Goods (Durable Goods (Not Elsewhere Classified)) * General Industries - Trade & Wholesale of General Goods (Flower) * General Industries - Trade & Wholesale of General Goods (Hardware, Equipment and Supplies - bolts, nuts, screws, saws, nails, staples, hand tools, etc) * General Industries - Trade & Wholesale of General Goods (Industrial Supplies (Not Elsewhere Classified)) * General Industries - Trade & Wholesale of General Goods (Semi - finished metal products - metal piping, tubing, nails, rods, etc) * General Industries - Trade & Wholesale of General Goods (Non - durable goods - e.g., food products, ice, rubber, etc) * General Industries - Trade & Wholesale of General Goods (Office and Commercial Furniture) * General Industries - Trade & Wholesale of General Goods (Paints and related equipment) * General Industries - Trade & Wholesale of General Goods (Photographic equipment, Photocopy machines, Microfilm, Typewriters, etc) * General Industries - Trade & Wholesale of General Goods (Piece Goods, Notions, and Other Dry Goods) * General Industries - Trade & Wholesale of General Goods (Commercial machines and equipment including food service and restaurant equipment) * General Industries - Trade & Wholesale of General Goods (Stationery, Office Supplies, Printing and Writing Paper) * General Industries - Trade & Wholesale of General Goods (Typewriter Stores - Sales, Rentals, and Service) * General Industries - Agri, Forestry & Fishing * General Industries - Trade & Wholesale of General Goods (Electrical Parts and equipment) *** * General Service - Membership Organizations (Civic, Social, and Fraternal Associations) * General Service - Membership Organizations (e.g., Non - sports) * General Service - Membership Organizations (e.g., Professional Sports Clubs) * General Service - Membership Organizations (e.g., Recreation Sports Clubs) * General Service - Miscellaneous Personal Services (Not Elsewhere Classified) * General Service - Other General Services * General Service - Photography Studios * General Service - Recreation Services (Not Elsewhere Classified) * General Service - Recycling & Waste Management * General Service - Sporting and Recreational Camps * General Service - Utility * General Service - Computer Network/Information Services * General Service - Health and Beauty Spas * General Service - Membership Organizations (Automobile Associations) * General Services - Cleaning, Maintenance, and Janitorial Services * General Services - Exterminating and Disinfecting Services * General Services - Laundries - Family and Commercial * General Services - Laundry, Cleaning, and Garment Services * General Services - Testing Laboratories (Non - Medical Testing) * General Services - Dry Cleaners * General Services - Buying and Shopping Services and Clubs * General Services - Carpet and Upholstery Cleaning *** * Medical Services - Doctors, Physicians & Vets - Optometrists and Ophthalmologists * Medical Services - Doctors, Physicians & Vets - Chiropractors * Medical Services - Doctors, Physicians & Vets - Dentists and Orthodontists * Medical Services - Doctors, Physicians & Vets - Doctors and Physicians (Not Elsewhere Classified) * Medical Services - Doctors, Physicians & Vets - Opticians, Optical Goods, and Eyeglasses * Medical Services - Doctors, Physicians & Vets - Osteopaths * Medical Services - Doctors, Physicians & Vets - Podiatrists and Chiropodists * Medical Services - Doctors, Physicians & Vets - Veterinary Services * Medical Services - Hospitals * Medical Services - Medical and Dental Laboratories * Medical Services - Nursing and Personal Care Facilities * Medical Services - Telemedicine & Telehealth *** * Others - Camper, Recreational and Utility Trailer Dealers * Others - Public Golf Courses * Others - Parking Lots, Parking Meters and Garages * Others - Package Tour Operators - Germany Only * Others - Motor Homes Dealers * Others - Motor Home and Recreational Vehicle Rentals * Others - Motion Picture and Video Tape Production and Distribution * Others - Mobile Home Dealers * Others - Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers (Not Elsewhere Classified) * Others - Information Retrieval Services * Others - Fireplace, Fireplace Screens and Accessories Stores * Others - Electric Vehicle Charging * Others - Snowmobile Dealers * Others - Computer Maintenance, Repair and Services (Not Elsewhere Classified) * Others - Trailer Parks and Campgrounds * Others - Automated Fuel Dispensers * Others - Truck and Utility Trailer Rentals * Others - Video Amusement Game Supplies * Others - Public Warehousing and Storage - Farm Products, Refrigerated Goods, Household Goods, and Storage * Others - Funding, Seed Capital Investment, and Venture Capital * Others - Cryptocurrency * Others - Books, Periodicals and Newspapers * Others - Boat Dealers * Others - Swimming Pools - Sales and Service * Others - Telegraph Services * Others - Tent and Awning Shops * Others - Export, Import or Trading of Goods * Others - Online: Advertising Services *** * Other Offline - Offline: Car Washes * Other Offline - Offline: Bowling Alleys * Other Offline - Offline: Billiard and Pool Establishments * Other Offline - Offline: Beauty and Barber Shops * Other Offline - Offline: Bands, Orchestras, and Miscellaneous Entertainers (Not Elsewhere Classified) * Other Offline - Offline: Automotive Service Shops (Non - Dealer) * Other Offline - Offline: Automotive Paint Shops * Other Offline - Offline: Automotive Body Repair Shops * Other Offline - Offline: Air Conditioning and Refrigeration Repair Shops * Other Offline - Offline: Advertising Services * Other Offline - Offline: Wrecking and Salvage Yards * Other Offline - Offline: Wholesale Clubs * Other Offline - Offline: Welding Services * Other Offline - Offline: Watch, Clock and Jewelry Repair * Other Offline - Offline: Video Game Arcades/Establishments * Other Offline - Offline: Towing Services * Other Offline - Offline: Tolls and Bridge Fees * Other Offline - Offline: Tire Retreading and Repair Shops * Other Offline - Offline: Specialty Cleaning, Polishing and Sanitation Preparations * Other Offline - Offline: Special Trade Contractors (Not Elsewhere Classified) * Other Offline - Offline: Shoe Repair Shops, Shoe Shine Parlors, and Hat Cleaning Shops * Other Offline - Offline: Service Stations (With or without Ancillary Services) * Other Offline - Offline: Roofing, Siding, and Sheet Metal Work Contractors * Other Offline - Offline: Record Stores * Other Offline - Offline: News Dealers and Newsstands * Other Offline - Offline: Motion Picture Theaters * Other Offline - Offline: Miscellaneous Repair Shops and Related Services * Other Offline - Offline: Masonry, Stonework, Tile Setting, Plastering and Insulation Contractors * Other Offline - Offline: Heating, Plumbing, and Air Conditioning Contractors * Other Offline - Offline: Furniture - Reupholstery, Repair, and Refinishing * Other Offline - Offline: Funeral Services and Crematories * Other Offline - Offline: Fast Food Restaurants * Other Offline - Offline: Emergency Services (GCAS) (Visa use only) * Other Offline - Offline: Electronics Repair Shops * Other Offline - Offline: Electrical Contractors * Other Offline - Offline: Electrical and Small Appliance Repair Shops * Other Offline - Offline: Eating Places and Restaurants * Other Offline - Offline: DVD/Video Tape Rental Stores * Other Offline - Offline: Drinking Places (Alcoholic Beverages) - Bars, Taverns, Nightclubs, Cocktail Lounges, and Discotheques * Other Offline - Offline: Door To Door Sales * Other Offline - Offline: Dance Halls, Studios and Schools * Other Offline - Offline: Concrete Work Contractors * Other Offline - Offline: Caterers * Other Offline - Offline: Carpentry Contractors *** * Platforms - Other Platforms * Platforms - Services Marketplace * Platforms - Goods Marketplace * Platforms - Goods Marketplace (with dedicated brand stores) * Platforms - Digital Content Marketplace & Appstore * Platforms - Super Apps * Platforms - Social Media *** * Professional Service - Credit Rating & Financial Data * Professional Service - App/Website/Software Development & Maintenance * Professional Service - BPO & KPO * Professional Service - Consulting & Coaching * Professional Service - Content Writing & Proof Reading * Professional Service - Counseling Services * Professional Service - Customer Survey & Market Research * Professional Service - Design & Architecture (Landscape and Horticultural Services) * Professional Service - Design & Architecture (Others) * Professional Service - Freelance (Graphic Design) * Professional Service - Freelance (Others) * Professional Service - Real Estate Sales & Brokerage * Professional Service - Printing, publishing and book binding (e.g., maps, newsletters, technical manuals) * Professional Service - Film development, photographic prints and enlargements * Professional Service - Photocopying, Reproduction, and Blueprinting Services * Professional Service - Typesetting, Plate Making and Related Services * Professional Services - Airports, Flying Fields, and Airport Terminals * Professional Services - Detective Agencies, Protective Services, and Security Services, including Armored Cars, and Guard Dogs * Professional Services - Employment Agencies and Temporary Help Services * Professional Services - Accounting, Auditing, Payroll, Bookkeeping Services * Professional Services - Architectural, Engineering, and Surveying Services * Professional Services - Legal Advices and Services * Professional Services - Tax Preparation Services * Professional Services - Motor Freight Carriers and Trucking - Local and Long Distance, Moving and Storage Companies, and Local Delivery Services * Professional Services - General Contractors - repair, remodeling, additions and alterations * Professional Services - Courier Services - Air and Ground, and Freight Forwarders *** * Professional Services (Govt) - Court Costs, Including Alimony and Child Support * Professional Services (Govt) - Fines * Professional Services (Govt) - Not elsewhere classified * Professional Services (Govt) - Postal * Professional Services (Govt) - Tax Payments * Professional Services (Govt) - U.S. Federal Government Agencies or Departments * Professional Services (Govt) - Bail and Bond Payments *** * Software as a Service - Other Software as a Service * Software as a Service - Employer on Record * Software as a Service - Benefits, Rewards & Loyalty * Software as a Service - Enterprise Software * Software as a Service - Education Technology (EdTech) *** * Telecommunication Services - Telecommunication Services, including Local and Long Distance Calls, Credit Card Calls, Calls Through Use of Magnetic - Stripe - Reading Telephones, and Fax Services *** * Travel & Leisure - Other Travel & Leisure (Timeshares) * Travel & Leisure - Other Transportation Services (Taxicabs and Limousines) * Travel & Leisure - Other Transportation Services (Railroads) * Travel & Leisure - Accommodation (Hotels, etc) * Travel & Leisure - Airlines (Not Elsewhere Classified) * Travel & Leisure - B2B Travel * Travel & Leisure - Boat Rentals and Leasing * Travel & Leisure - Destination Management Companies * Travel & Leisure - Event Ticketing * Travel & Leisure - Marinas, Marine Service, and Supplies * Travel & Leisure - Other Transportation Services (Ambulance Services) * Travel & Leisure - Travel Agencies & OTAs * Travel & Leisure - Tourist Attractions (Tourist Attractions and Exhibits) * Travel & Leisure - Tourist Attractions (Aquariums, Seaquariums, Dolphinariums, and Zoos) * Travel & Leisure - Other Transportation Services (Automobile Rental Agency) * Travel & Leisure - Other Transportation Services (Bus Lines) * Travel & Leisure - Other Transportation Services (Local and Suburban Commuter Passenger Transportation, Including Ferries) * Travel & Leisure - Other Transportation Services (Passenger Railways) * Travel & Leisure - Tourist Attractions (Amusement Parks, Circuses, Carnivals, and Fortune Tellers) * Travel & Leisure - Cruise Lines * Travel & Leisure - Other Travel & Booking services (e.g., Visa) * Travel & Leisure - Other Transportation Services (Transportation Services (Not Elsewhere Classified)) # Tazamatch Source: https://developer.tazapay.com/api-reference/appendix/tazamatch These error codes are specific to Tazamatch requests. For errors common to all Tazapay APIs — such as authentication, rate limiting, and request formatting — refer to [Generic Error Codes](/API-Reference/appendix/error-codes/generic). *** ### GET /v3/verification/payee/metadata | Code | Message | HTTP Status | | ----- | ------------------------------- | ----------- | | 50006 | Please provide a valid country | 400 | | 50007 | Please provide a valid currency | 400 | | 50012 | This corridor is not supported | 400 | *** ### POST /v3/verify/payee #### Validation Errors | Code | Message | HTTP Status | | ----- | --------------------------------------------------------- | ----------- | | 50000 | Please provide a valid type | 400 | | 50001 | Please provide a valid name | 400 | | 50002 | Please provide a valid email | 400 | | 50003 | Please provide a valid phone | 400 | | 50004 | Please provide a valid destination | 400 | | 50005 | Please provide a valid destination type | 400 | | 50006 | Please provide a valid country | 400 | | 50007 | Please provide a valid currency | 400 | | 50008 | Please provide a valid account number | 400 | | 50009 | Please provide a valid local payment network | 400 | | 50010 | Please provide a valid bank identifier | 400 | | 50013 | Please provide the required bank fields for this corridor | 400 | | 50014 | Please provide a valid value for the required bank fields | 400 | | 50015 | Please provide the required beneficiary fields | 400 | *** ### GET /v3/verify/payee/ | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------- | ----------- | | 50100 | Please provide a valid verification ID starting with pyv\_ | 400 | *** #### Corridor Not Supported | Code | Message | HTTP Status | | ----- | ------------------------------ | ----------- | | 50012 | This corridor is not supported | 400 | *** #### Service Errors | Code | Message | HTTP Status | | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 50016 | We are temporarily unable to process your verification request as our verification provider is rate limiting requests. Please try again shortly. | 503 | | 50017 | We were unable to securely process your verification request due to an internal error. Please try again, and contact [support@tazapay.com](mailto:support@tazapay.com) if the problem persists. | 500 | | 50018 | Our verification provider is temporarily unavailable. Please try again shortly. | 503 | *** # Update Beneficiary Source: https://developer.tazapay.com/api-reference/appendix/update-beneficiary Error codes for PUT /v3/beneficiary/{id} ### PUT v3/beneficiary/\{id} | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 20161 | Field is required and must be a valid beneficiary id. Example: bnf\_xid | 400 | | 20323 | Please provide a valid existing beneficiary id | 400 | | 20324 | Field is required, please provide a valid tax\_id | 400 | | 20325 | Restricted field update attempt: %s | 400 | | 20193 | You do not have permission to access this resource | 403 | | 3895 | Account number is required and cannot be empty | 400 | | 3896 | Account number must be alphanumeric and between 4-34 characters | 400 | | 3900 | IBAN is required and cannot be empty | 400 | | 3901 | IBAN must be between 15-34 characters | 400 | | 3902 | IBAN must be between 15-34 characters and start with 2 letters, 2 digits, followed by alphanumeric characters | 400 | | 3903 | IBAN country code is not supported | 400 | | 3904 | IBAN country code does not match the destination country code | 400 | | 3905 | IBAN length is invalid for the specified country | 400 | | 3906 | IBAN checksum validation failed. Please verify that the IBAN is correct | 400 | | 3907 | IBAN country code is not supported by Tazapay | 400 | | 3910 | SWIFT code is required and cannot be empty | 400 | | 3911 | SWIFT code must be either 8 or 11 characters with format: 4 letters (bank), 2 letters (country), 2 alphanumeric (location), and optional 3 alphanumeric (branch) | 400 | | 3912 | SWIFT code has invalid location code. Characters 7 and 8 cannot be '00' | 400 | | 3913 | SWIFT country code is not supported by Tazapay | 400 | | 3915 | BIC code is required and cannot be empty | 400 | | 3916 | BIC code must be either 8 or 11 characters with format: 4 letters (bank), 2 letters (country), 2 alphanumeric (location), and optional 3 alphanumeric (branch) | 400 | | 3917 | BIC code has invalid location code. Characters 7 and 8 cannot be '00' | 400 | | 3918 | BIC country code is not supported by Tazapay | 400 | | 3920 | Sort code is required and cannot be empty | 400 | | 3921 | Sort code must be exactly 6 numeric digits | 400 | | 3925 | ABA routing number is required and cannot be empty | 400 | | 3926 | ABA routing number must be exactly 9 numeric digits | 400 | | 3927 | ABA routing number has invalid federal reserve prefix (first 2 digits) | 400 | | 3928 | ABA routing number checksum validation failed (3-7-1 algorithm) | 400 | | 3930 | IFSC code is required and cannot be empty | 400 | | 3931 | IFSC code must be exactly 11 characters (4 letters, '0', 6 alphanumeric) | 400 | | 3935 | BSB code is required and cannot be empty | 400 | | 3936 | BSB code must be exactly 6 numeric digits | 400 | | 3940 | Bank code (Brazil) is required and cannot be empty | 400 | | 3941 | Bank code (Brazil) must be either 3 digits (COMPE) or 8 digits (ISPB) | 400 | # Update Checkout Session Source: https://developer.tazapay.com/api-reference/appendix/update-checkout Error codes for PUT /v3/checkout/{id} ### PUT v3/checkout/\{id} | Code | Message | HTTP Status | | ----- | ------------------------------------------------------------------------------------ | ----------- | | 15500 | Checkout ID field is required and must be a valid ID, Example: chk\_id | 400 | | 15515 | Request object passed for this API request is failing. Please provide valid metadata | 400 | # Update Customer Source: https://developer.tazapay.com/api-reference/appendix/update-customer Error codes for PUT /v3/customer ### PUT v3/customer | Code | Message | HTTP Status | | ---- | ------------------------------------- | ----------- | | 2310 | Account id is missing | 400 | | 2311 | Customer id is missing | 400 | | 2312 | Customer already exist with same name | 400 | # Update Entity Source: https://developer.tazapay.com/api-reference/appendix/update-entity Error codes for PUT /v3/entity/{id} ### PUT v3/entity/\{id} | Code | Message | HTTP Status | | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | 3006 | A required field is missing, check our KYB API body parameters for required fields | 400 | | 3019 | Unable to update since the KYB is already completed. please contact us at [ops@tazapay.com](mailto:ops@tazapay.com) if there is a change in the entity's details. | 400 | | 3025 | KYB application not found | 404 | | 3028 | Unable to update since the KYB is already submitted. please contact us at [ops@tazapay.com](mailto:ops@tazapay.com) if there is a change | 400 | | 3036 | We regret to inform you that you currently do not have the necessary authorization to access this resource | 403 | # Update Lightning Invoice Source: https://developer.tazapay.com/api-reference/appendix/update-lightning-invoice Error codes for PUT /v3/lightning_invoice_bolt11/{id} ### PUT v3/lightning\_invoice\_bolt11/\{id} | Code | Message | HTTP Status | | ----- | ------------------------------------------------ | ----------- | | 20471 | Field is required and must be a valid invoice id | 400 | | 20472 | Invoice status is invalid for this operation | 400 | | 20474 | Please provide a valid metadata | 400 | # Update Payin Source: https://developer.tazapay.com/api-reference/appendix/update-payin Error codes for PUT /v3/payin/{id} ### PUT v3/payin/\{id} | Code | Message | HTTP Status | | ----- | --------------------------------------------------------------------------------------------- | ----------- | | 15508 | Please provide a valid URL | 400 | | 15526 | Payin Id is required. Please check whether id provided is in correct format. Example: pay\_id | 400 | | 15526 | Payin Id is required. Please check whether id provided is in correct format. Example: pay\_id | 404 | | 15527 | Please provide a valid customer id | 400 | | 19017 | Payin status is not in valid state to initiate payment | 409 | | 19626 | The payin is either no longer active or has been cancelled | 409 | # Update Payment Attempt Source: https://developer.tazapay.com/api-reference/appendix/update-payment-attempt Error codes for PUT /v3/payment_attempt/{id} ### PUT v3/payment\_attempt/\{id} | Code | Message | HTTP Status | | ----- | -------------------------------------------------------------------------------------------- | ----------- | | 15515 | Request object passed for this API request is failing. Please provide valid metadata | 400 | | 19100 | Invalid payment\_attempt\_id, should have prefix 'pat\_' and should be followed by valid xid | 400 | # Update Refund Source: https://developer.tazapay.com/api-reference/appendix/update-refund Error codes for PUT /v3/refund/{id} ### PUT v3/refund/\{id} | Code | Message | HTTP Status | | ----- | ---------------------------------------------------------------------------------- | ----------- | | 30050 | Invalid refund\_id, should have prefix 'rfd\_' and should be followed by valid xid | 400 | | 30160 | Field metadata is required, please provide a valid metadata | 400 | | 30161 | Cannot update a refund object which was cancelled already | 409 | # Upload Document Source: https://developer.tazapay.com/api-reference/appendix/upload-document Error codes for POST /v3/document ### POST v3/document | Code | Message | HTTP Status | | ----- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | | 15560 | Document Id is required. Example: doc\_ | 400 | | 19018 | Payin is not funded. Please ensure that the transaction is funded. | 409 | | 19025 | URL you have provided could not be reached | 404 | | 19026 | URL you have provided does not have a downloadable document available | 404 | | 19027 | Document missing. Please verify whether essential transactional documents or any additional documents have been attached. | 400 | # Upload Document to Tazapay Source: https://developer.tazapay.com/api-reference/appendix/upload-document-to-tazapay Error codes for POST /v3/metadata/doc/upload ### POST v3/metadata/doc/upload | Code | Message | HTTP Status | | ---- | ----------------------------------------------------------------- | ----------- | | 1020 | Invalid file format/empty file, please provide a valid file\_name | 400 | | 1100 | Unsupported file type. Please upload a valid file. | 400 | | 1101 | Empty or Invalid file name. Please provide a valid file name. | 400 | # Webhook Authentication Source: https://developer.tazapay.com/api-reference/appendix/webhook-authentication At Tazapay, we want to ensure that every webhook sent to our merchants is authentic and unaltered. Each webhook request header includes a signature generated using the event ID, payload, and timestamp. Because the signature is tied to the payload, any tampering invalidates the signature, preventing malicious modifications. Additionally, the timestamp in the signature helps mitigate [replay attacks](#avoiding-replay-attacks). Use this mechanism to confirm that incoming webhooks originate from Tazapay and have not been compromised in transit. *** ## Steps to Generate the Webhook Signature ### 1. Extract the `event_id` The `event_id` is a unique identifier for each webhook event. It is part of the webhook request payload. Example of how `event_id` is structured: ```json theme={null} { "id": "evt_cv82n92p51c5jo1f5vfg", "data":{} } ``` ### 2. Extract the Timestamp The time when the webhook request was received. Extract the created\_at field from the webhook response. Please note that we need to extract the `created_at` field that is outside the data json block. The timestamp will be in RFC3339Nano format. ```Text json theme={null} { "created_at": "2025-03-11T12:25:08.284979602Z", "data":{} } ``` ### 3. Concatenate Data for Signing Once you have the event\_id and the timestamp, you need to concatenate them with the payload into a single string. This concatenated string will be used to generate the signature. ```Text json theme={null} ``` Example - ``` evt_cv82n92p51c5jo1f5vfg{"type":"payout.created","id":"evt_cv82n92p51c5jo1f5vfg","object":"event","created_at":"2025-03-11T12:25:08.284979602Z","data":{"created_at":"2025-03-11T12:25:05.960717Z","beneficiary_details":{"address":{"line1":"test","line2":"test","postal_code":"10038","city":"test","state":"test","country":""},"destination_details":{"bank":{"bank_codes":{"aba_code":"test","swift_code":"test"},"account_number":"test","bank_name":"test","country":"US","currency":"USD"},"type":"bank"},"phone":{"calling_code":"1","number":"12312312312"},"name":"test","email":"test@examplee.com","type":"individual","tax_id":"test"},"payout_fx_transaction":{"initial":{"currency":"USD","amount":100},"final":{"currency":"USD","amount":100},"id":"fx_cv82n89445nl3tkns2ug","object":"fx_transaction","exchange_rate":1},"type":"local","status":"processing","purpose":"PYR001","id":"pot_cv82n88epb2o04b90t9g","holding_currency":"USD","currency":"USD","beneficiary":"bnf_crv7poph1l071n2fkcmg","object":"payout","balance_transaction":"btr_cv82n8gepb2o04b90tdg","amount":100}}2025-03-11T12:25:08.284979602Z ``` ### Generate HMAC-SHA256 Signature Once you have concatenated the data, you will use HMAC-SHA256 to generate the signature. HMAC (Hash-based Message Authentication Code) is a cryptographic function that ensures data integrity and authenticity by using a secret key and a hashing algorithm. To generate the signature: 1. Concatenate the event\_id, payload, and timestamp into a single string. 2. Use HMAC-SHA256 to hash the concatenated string using your secret key. 3. You can find the secret key on the merchant dashboard on the Settings > Webhooks > secret token. Click on reveal to view the secret token 4. Generate the signature in Base64 format. Example of how the signature will look like for the above concatenated string for secret key `YKzhhJM4gd8s5MS1LVvWbqSyJqLPvr7j` - ``` T2tZvRcMuZWVyDZrorBlPd7u8XKBx8RTWUSGuTakZqQ= ``` ## Verify the signature Once you have generated the signature on your end, you can match it with the signature sent by Tazapay in the webhook header in the field name - `signature`. If both of the signatures match , that means that the webhook is sent by Tazapay and has not been tampered with while transmission. ## Avoiding Replay Attacks A replay attack occurs when an attacker intercepts a valid payload and its signature, then retransmits them. To mitigate such attacks, Tazapay includes a timestamp in the `signature` header. Since this timestamp is part of the signed payload, it is also verified through the signature. This ensures that an attacker cannot modify the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, your application should reject the payload. You can allow a tolerance of 10 minutes between the timestamp and the current time to avoid replay attacks. # Webhook Retry Policy Source: https://developer.tazapay.com/api-reference/appendix/webhook-retry-policy If Tazapay does not receive a 2xx status from your endpoint as an acknowledgement of successful webhook delivery, it keeps retrying. Tazapay keeps retrying for the below error codes: * StatusBadRequest - 400 * StatusNotFound - 404 * StatusRequestTimeout - 408 * StatusConflict - 409 * StatusPreconditionFailed - 412 * StatusInternalServerError - 500 The time between each retry increases exponentially by a power of 2 with jitter till a period of 8 hours. The first retry starts after 1 second of original webhook delivery. This process is repeated 3 times. You can receive a retried webhook upto 24 hours from the delivery of the first webhook. # Webhooks Guide Source: https://developer.tazapay.com/api-reference/appendix/webhooks-guide Tazapay provides full control and visibility over your webhook events. This guide explains how to: * Configure webhook endpoints * Enable/Disable webhooks endpoints * View webhook event logs * Re-trigger webhook events * Authenticate webhooks * Manage user permissions *** ## Configuring Webhooks on Tazapay To start receiving webhook events, you must first configure your webhook endpoint. ### Steps to Configure 1. Go to `Settings > Webhooks` 2. Click **Add Webhook URL** 3. Fill in the following fields: | Field | Description | | --------------------- | ----------------------------------------------------------------------- | | `Name` | Friendly identifier for your webhook | | `URL` | The full endpoint URL on your server | | `Events to Subscribe` | Select the event types you want (e.g. `checkout.paid`, `payout.failed`) | Once confirmed , Tazapay will begin sending events to the specified URL when matching events occur. *** ## Enabling or Disabling Webhooks You can toggle the active/inactive status of a webhook at any time. ### How to Toggle 1. Navigate to `Settings > Webhooks` 2. Select the webhook you'd like to manage 3. Use the **Enable/Disable** toggle on the webhook listing page or settings option inside the webhook detail page to manage the status of the webhook. ### Behavior * **Enabled**: Events matching the selected types will be sent * **Disabled**: No events will be sent until re-enabled > Disabling a webhook does not delete it or affect previously sent events. ## Viewing Webhook Logs You can inspect detailed logs for each webhook event via the dashboard. ### Accessing Logs 1. Go to `Settings > Webhooks` 2. Click the webhook name or select `View details` ### Webhook Details * **Webhook Name & URL** * **Status**: Enabled/Disabled * **Secret Token** * **Total Events Triggered** * **Event Logs Table** with filters and search ### Log Entry Fields | Field | Description | | ------------------- | ---------------------------------------------------------------- | | `Last Attempt Date` | Timestamp of last delivery | | `Event ID` | Unique ID, e.g. `evt_ctc0lfqe4e771g7bbof0` | | `Response Code` | HTTP status returned by your server (e.g., `200`, `503`) | | `Event Type` | Event name like `checkout.paid` or `payment.failed` | | `Reference Id` | Payment id related to the webhook e.g. `chk_d1382lo4jjk32r7ri8r` | ### Filtering and Searching You can filter logs by: * Created Date - Timestamp when the webhook event was created. * Event type * Response code You can also search by **Event ID** or **Payment ID**. *** ## Re-triggering Webhook Events You can re-send webhook events if they were missed or failed. ### Re-trigger a Single Event Click the **Resend** button next to the event log. A loading spinner will show while the event is being resent. > Limit: Each event can be resent up to 3 times within 24 hours. ### Re-trigger Multiple Events 1. Select multiple log entries using checkboxes. 2. Click **Bulk Resend**. 3. Events will be resent one by one in the background. > Tip: Use the sandbox environment to test webhooks before retrying in production. *** ## Authenticating Webhooks Tazapay signs each webhook request. You should verify the signature to ensure the webhook came from us. ### How It Works 1. Each request includes a `webhook-signature` header. 2. You need to generate the same signature at your end and verify it with the one sent with the webhook 3. Signature is build using event\_id, payload, timestamp and the secret token 👉 [View detailed implementation guide](/api-reference/appendix/webhook-authentication) *** ## Managing Permissions You can restrict access to webhook logs and actions by managing team permissions. ### Manage via Dashboard Go to `Settings > Manage Team > Edit` | Permission | Default for New Users | | ----------------------- | --------------------- | | View Webhooks | ✅ Enabled | | Edit/Retrigger Webhooks | ❌ Disabled | | View Secret Token | ❌ Disabled | | Regenerate Secret Token | ❌ Disabled | > If a user doesn’t have access to specific transactions, they won’t see the related webhook events. *** ## Testing in Sandbox Use the **Sandbox Environment** to test webhook integration safely. * Supports all webhook events * Avoids triggering production workflows * Prevents rate limit issues or costs *** ## Support If you need help: 📩 Email us at [support@tazapay.com](mailto:support@tazapay.com) # Blur Event Source: https://developer.tazapay.com/api-reference/javascript-sdk/blur-event The blur event is triggered when the embed loses focus. ## Method Parameters 1. `event` - mandatory\ The name of the event, in this case `blur` 2. `handler` - mandatory\ handler(event) => void is a callback function that a merchant will provide that will be called when the event is fired. When called it will be passed an event object with the following properties: | Field | Sub-field | Type | Description | | :-------- | :-------- | :----- | :------------------------------------------------------------- | | embedType | | string | The type of embed that emitted this event. In this case `card` | ## Handling an embed blur event ```javascript Javascript theme={null} cardEmbed.on('blur', function(event) { // Handle blur event }); ``` # Button Styles Source: https://developer.tazapay.com/api-reference/javascript-sdk/button-styles ## Button Styling We provide plenty of styling options for the buttons. ```json Style Object expandable theme={null} style: { "primaryButton_margin": "0px 0px 0px 0px", "primaryButton_padding": "1rem", "primaryButton_outline": "none", "primaryButton_borderWidth": "2px", "primaryButton_borderColor": "black", "primaryButton_borderStyle": "solid", "primaryButton_borderRadius": "20px", "primaryButton_width": "100%", "primaryButton_height": "3rem", "primaryButton_fontFamily": "Arial, sans-serif", "primaryButton_fontSize": "14px", "primaryButton_fontWeight": "600", "primaryButton_color": "white", "primaryButton_background": "blue", "primaryButton_boxSizing": "border-box" } ``` You can also use above styling options for various button states like hover, processing and disabled. ```json Style Object theme={null} style: { "primaryButton-hover_background": "lightblue", "primaryButton-processing_background": "darkgray", "primaryButton-disabled_background": "gray", } ``` You can style primary buttons as well as secondary buttons. # Card Embed Methods Source: https://developer.tazapay.com/api-reference/javascript-sdk/card-embed-methods # cardEmbed.lock() Source: https://developer.tazapay.com/api-reference/javascript-sdk/cardembedlock Disabled the card embed for user input ```javascript JavaScript theme={null} cardEmbed.lock(); ``` # cardEmbed.unlock() Source: https://developer.tazapay.com/api-reference/javascript-sdk/cardembedunlock Enables a locked card embed for input ```javascript JavaScript theme={null} cardEmbed.lock(); ...... ...... cardEmbed.unlock(); ``` # Change Event Source: https://developer.tazapay.com/api-reference/javascript-sdk/change-event The change event is triggered when the value of the embed changes. The payload of this event contains keys specific to the embed you are using ## Method Parameters 1. `event` - mandatory\ The name of the event, in this case `change` 2. `handler` - mandatory\ handler(event) => void is a callback function that a merchant will provide that will be called when the event is fired. When called it will be passed an event object with the following properties: | Field | Sub-field | | Type | Description | | :-------- | :--------------- | :---- | :------ | :---------------------------------------------------------------------------------------------------------------------- | | embedType | | | string | The type of embed that emitted this event. In this case card | | empty | | | boolean | true if the embed is empty | | complete | | | boolean | true if the embed is well-formed and potentially complete. That is the merchant can use this to enable their pay button | | error | | | json | Any error that we surface to the customer while they are typing | | value | | | json | | | | cardholder\_name | | string | Cardholder name entered by the customer on the embed | | | expiry | | json | Card Expiry Details | | | | month | integer | Number representing the card’s expiration month | | | | year | integer | Four-digit number representing the card’s expiration year. | | | last4 | | string | The last 4 digits of the card | | | first6 | | string | The first 6 digits of the card | | scheme | | | enum | Card scheme - visa, mastercard, american\_express | ## Handling a card embed change event ```javascript Javascript theme={null} cardEmbed.on('change', function(event) { if (event.complete) { // enable payment button } else if (event.error) { // show validation to customer } }); ``` ## Handler event object ```json Object theme={null} { complete: false, brand: 'visa', embedType: 'card', empty: false, error: { cardNumber: "Enter the card number", expiry: "Enter valid expiry date", cvv: "", name: "" }, value: { cardholder_name: "" } } ``` # Container Styles Source: https://developer.tazapay.com/api-reference/javascript-sdk/container-styles You have the ability to the customise the UI component to suit your branding and theme. ## Define sizing constraints for payment element ```json Style Object theme={null} style: { "container_minWidth": "0%", "container_maxWidth": "750px", "container_minHeight": "300px", "container_maxHeight": "99999px", "container-iframe_minWidth": "100%", "container-iframe_maxWidth": "750px", "container-iframe_minHeight": "300px", "container-iframe_maxHeight": "99999px", } ``` The payment element has a parent wrapper container and a child iframe element. ## Define additional customisation for payment element ```json Style Object theme={null} style: { "container_zIndex": "1", "container_padding": "1rem", "container_background": "rgb(0 0 0 / 0.7)", //use for popup "container_backdrop": "blur(4px)", "container-iframe_background": "transparent", "container-iframe-loading_background": "#F4F5F7", "container-iframe_borderRadius": "4px", "container-iframe_boxshadow": "0px 10px 15px rgba(226, 232, 240, 0.32), 0px 4px 6px rgba(226, 232, 240, 0.5)", } ``` # Flow Source: https://developer.tazapay.com/api-reference/javascript-sdk/custom-flow ## Step 1: Set up tazapay.js The Card Embed is automatically available as a feature of tazapay.js. Include the tazapay.js script on your checkout page by adding it to the head of your HTML file. Always load tazapay.js directly from js.tazapay.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself. ```html Production (livemode) theme={null} Checkout ``` ```html Sandbox (Testmode) theme={null} Checkout ``` **Dynamic Injection** Before injecting the SDK dynamically, please use the following event listener to determine when the script has finished loading. ```javascript theme={null} window.addEventListener('tazapaySDKReady', () => { // continue to use library by following below from step 2 here }); ``` ## Step 2: Initialising tazapay.js ```html HTML theme={null} const tazapay = await window.tazapay('pk_test_TYooMyTiskhfuvdEDq54NiTphI7jx'); ``` The above code creates an instance of the Tazapay object inside the merchant’s client-side project. This created object now serves as an entry-point to the rest of Tazapay’s JS SDK. ## Step 3: Add the card embed to your payment page The `Card Embed` needs a place to live on your payment page. Create an empty DOM node (container) with a unique ID in your payment form: ```html Javascript theme={null}
``` ## Step 4: Create an instance of the card embed and mount it to the already created DOM containers ```javascript Javascript theme={null} const embeds = tazapay.embeds(); let configuration = { style: {}, showLabels: false, hideErrors: false, layout: "two-rows", cvvMask: true, customPayButton: false, } const card = embeds.create("card",configuration); card.mount("card-embed"); ``` * The mount function is a part of the library which attaches the UI component to the DOM container with unique ID. * This mounting of the card component does require the existence of a client\_token which is a unique reference for the transaction. ### Configurations You can pass the following configurations while instantiating the card embed. | Property | Description | Possible Values | | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | | `style` | Customize the look of the user interface. | Refer to the style guide here. | | `showLabels` | Show field labels like Card Number, Expiry Date, and CVV on top of each input field. Off by default; set to true to enable. | `true`/`false` | | `hideErrors` | Hide error messages on the embed as the customer types. Off by default; set to true to hide errors (manage errors in "change" event). | `true`/`false` | | `layout` | Arrange the card number, expiry, cvv fields in rows. Default is "two-rows" (card number on top, expiry date and CVV below). Options include "one-row" (all fields in a single row) and "three-rows" (each field on its own row). | `"one-row"`, `"two-rows"`, `"three-rows"` | | `cvvMask` | Mask the CVV field. On by default. | `true`/`false` | | `customPayButton` | Use a custom pay button instead of the default. Off by default; refer to the integration guide to enable. | `true`/`false` | ## Step 5: Listening to events Tazapay's card embed will automatically validate and display any errors as the customers type. You can listen to these events ## Step 6: Listen for the click event on the Pay button You can either choose to use your own pay button or use the pay button of the card embed. ### Using the card embed's inbuilt pay button * The SDK provides an easy-to-use event called "payButtonClick" that gets triggered whenever the user clicks on the "Pay" button. You can "listen" for this event and execute your custom code in response. * To set up your event listener, you'll need to attach it to the card object. ```javascript Javascript theme={null} card.on("payButtonClick", function(d) { // This code block will run when the inbuilt "Pay" button is clicked. }); ``` ### Using your custom pay button 1. First off, let's make sure the inbuilt pay button isn't visible, since you're going to use your own custom button. You can do this by adjusting the `customPayButton` in your configuration in Step 4. 2. Enable the pay button to accept clicks by listening to the `change` event. Show the pay button only if complete is `true`. And trigger Step 7 when the customer clicks that pay button. *Additional Guide: Change event* ## Step 7: Submitting the payment to Tazapay to create a charge Disable the Pay Button for further clicks and perform the following actions once the customer clicks on the Pay Button ### Fetching the client-token (server-side) 1. Submitting the payment to create a charge will require a `client_token` which is the unique identifier for a payin or a customer session on your website/application. 2. This unique token is generated as a response of the payin created by a server call to Tazapay's payin API. ```json JSON theme={null} { "status": "success", "message": "", "data": { "client_token": "RMkE8f2FJuRLTZbh-NyEiYoEOEMbwOS4zMbMwFUTTs=", } } ``` > **Idempotent Payin Sessions:** It is required for you to make sure that the requests to create payin are idempotent. For the value of the idempotency key, you can pass the unique order number on your system. > You can refer to this guide for the implementation. This will ensure only unique payin are created corresponding to a unique customer journey on your website/application. ### Call the confirmPayment() method After you have retrieved the client\_token, call the confirmPayment() method from the SDK to submit a payment to Tazapay to create a charge. The function takes the following parameters as input | Parameter | Mandatory / Optional | Description | | :----------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client\_token | Mandatory | Refer response of the payin API | | payment\_method\_details | Mandatory | This contains two parameters - `type` and `card` | | customer\_details | Conditionally Mandatory | Only required if the customer\_details are not passed from the server-side | | billing\_details | Conditionally Mandatory | Refer to the guide here. | | success\_url | Mandatory | The customer will be redirected to this URL after a successful charge creation. The customer may be redirected externally to authenticate themselves for 3DS. | | cancel\_url | Mandatory | The customer will be redirected to this URL after a failed charge. The customer may be redirected externally to authenticate themselves for 3DS. | ```javascript Javascript expandable theme={null} const details = { payment_method_details: { type: "card", card: { card: card, // card is a variable which contains card instance, assigned in step 4. }, }, customer_details: { country: "", email: "", name: "", phone: { calling_code: "", number: "" } }, billing_details: { name: "", address: { line1: "", line2: "", city: "", state: "", country: "", postal_code: "", }, phone: { calling_code: "", number: "", } } // pass any other relevant fields }; tazapay.confirmPayment(client_token, details) // tazapay is a variable in step 2. .then((resp) => { console.log("confirmPayment promise resolved: ", resp); // handle payment success flow, like redirecting to success/thankyou page etc. }) .catch((error) => { console.log("confirmPayment promise rejected: ", error); // handle payment error, like display error message if it caused by customer, stop custom pay button loading, etc. }); ``` ## Step 8: Display success / failure message to the customer `tazapay.confirmPayment()` will return a `Promise` which resolves with a `result` object. The object has either: * `result.payin` * This is returned when the charge (payment) is successful. * This essentially contains the response of GET /v3/payin * `result.error` * This is returned when there is an error during payment processing or when a charge fails. * The `error` object returns the following properties: | Field | type | Description | | :---- | :----- | :-------------------------------- | | error | string | Buyer Comprehension for the error | | code | string | Error code | In case the customer is redirected to an external site to authenticate, the promise will never resolve and the customer will be redirected to the `success_url` passed by you. Make sure to display appropriate message on your success and failure URLs. ## Step 9: Handle post-payment events Tazapay sends a `payin.succeeded` event as soon as the funds are received from the customer. Use the webhook\_url field in the payin API to receive these events and run actions (for example, sending an order confirmation email to your customers, logging the sale in a database, starting a shipping workflow, etc.) In case of a failed payment attempt, Tazapay sends a `payment_attempt.failed` event with the reason of failure. | Event | Description | Next Steps | | :---------------------- | :-------------------------------- | :------------------------------------------------------------ | | payin.succeeded | The charge creation is successful | Fulfill the goods or services that the customer purchased | | payment\_attempt.failed | The charge creation failed | Re-enable the pay button and allow the customer to pay again. | # Developer Recomendations Source: https://developer.tazapay.com/api-reference/javascript-sdk/developer-recomendations > Tazapay recommends creating a checkout session (using the POST /v3/checkout endpoint) as soon as you have the necessary data from the customer (name, country and email). This reduces the time to load Tazapay's UI component for the customer. ## Reduce the wait time for your customers Use preloading to load payment module in advance and reduce wait time for users. ```javascript JavaScript theme={null} window.addEventListener("load", (event) => { //Preload tazapay payment UI as soon as the document loads window.tazapay.preload(); // no arg required here }); ``` ```javascript JavaScript theme={null} //Call below method only once the clientToken is available const options: { clientToken: "...", } window.tazapay.checkout(options); ``` # Element Styles Source: https://developer.tazapay.com/api-reference/javascript-sdk/element-styles ## Customise text colors ```json Style Object theme={null} style: { "textprimary_color": "#27303F", "textprimary-active_color": "#156B8", "link_color": "rgba(55, 151, 187, 1)", } ``` ## Customise the Spinner color ```json Style Object theme={null} style: { "spinner_gradient": "white 0deg, rgba(39, 83, 107, 1) 360deg", "spinnerhead_color": "#26536B", } ``` ## Payment method list styling ```json Style Object theme={null} style: { "listitem_border": "1.5px solid #E2E8F0", "listitem_borderRadius": "0px", "listitem_background": "transparent", "listitem-hover_border": "1.5px solid #156B8A", "listitem-hover_background": "#FBFDFE", "listitem-active_border": "1.5px solid #156B8A", "listitem-active_background": "#FBFDFE", } ``` ## Enable Radio Buttons for Payment Option ```json Style Object theme={null} style: { "listitemRadio-display": "visible", "listitemRadio_border": "1px solid #97A6BA", "listitemRadio-checked_border": "1px solid #1B89B1", "listitemRadio-checked_background": "#156B8A", } ``` ## Icon Styling ```json Style Object theme={null} style: { "iconSuccess_background": "#3538CD", "iconSuccess_foreground": "white", "iconProgress_background": "#3538CD", "iconFail_background": "#BA1A1A", } ``` Style the icons that will be shown on success and failure screens # Escape Event Source: https://developer.tazapay.com/api-reference/javascript-sdk/escape-event The escape event is triggered when the customer presses the escape key within the embed. ## Method Parameters 1. `event` - mandatory\ The name of the event, in this case `escape` 2. `handler` - mandatory\ handler(event) => void is a callback function that a merchant will provide that will be called when the event is fired. When called it will be passed an event object with the following properties: | Field | Sub-field | Type | Description | | :-------- | :-------- | :----- | :------------------------------------------------------------- | | embedType | | string | The type of embed that emitted this event. In this case `card` | ## Handling an embed escape event ```javascript Javascript theme={null} cardEmbed.on('escape', function(event) { // Handle escape event }); ``` # Focus Event Source: https://developer.tazapay.com/api-reference/javascript-sdk/focus-event The focus event is triggered when the embed gains focus. This can happen when a user clicks on an input element, or uses the keyboard (like the Tab key) to navigate to it. ## Method Parameters 1. `event` - mandatory\ The name of the event, in this case `focus` 2. `handler` - mandatory\ handler(event) => void is a callback function that a merchant will provide that will be called when the event is fired. When called it will be passed an event object with the following properties: | Field | Sub-field | Type | Description | | :-------- | :-------- | :----- | :------------------------------------------------------------- | | embedType | | string | The type of embed that emitted this event. In this case `card` | ## Handling an embed focus event ```javascript Javascript theme={null} cardEmbed.on('focus', function(event) { // Handle focus event }); ``` # How the SDK Works Source: https://developer.tazapay.com/api-reference/javascript-sdk/how-the-sdk-works Your customer initiates a checkout. When your customer chooses to checkout, your server sends a request to the checkout API to create a new checkout session. A checkout session is created and it returns a token. The UI component is instantiated in your customer’s browser using Tazapay.js library and the token of the checkout session. The customer selects their preferred payment method. They then fill out the payment details and click on `Pay`. This completes the checkout experience. Tazapay notifies your server when the payment is successfully received using webhooks. The webhook data contains the successful payment state as well as the unique transaction number for you to reconcile and perform further necessary actions. How Tazapay's Javascript SDK works # Input Styles Source: https://developer.tazapay.com/api-reference/javascript-sdk/input-styles ## Input Field Styling (only for Card Form) We provide plenty of styling options for the Input fields ```json Style Object expandable theme={null} style: { "input-base_margin": "0px 0px 0px 0px !important", "input-base_padding": "20px", "input-base_outline": "none", "input-base_borderWidth": "0px", "input-base_borderColor": "black", "input-base_borderStyle": "solid", "input-base_borderRadius": "5px", "input-base_width": "100%", "input-base_height": "45px", "input-base_fontFamily": "Arial, sans-serif", "input-base_fontSize": "14px", "input-base_fontWeight": "600", "input-base_color": "black", "input-base_background": "white", "input-base_boxShadow": "0px 0px 2px 0px #80808080 inset", "input-base_boxSizing": "border-box", } ``` You can also use above styling options for various input field states like focus and error. These style properties can also be used for the validation error message shown below input fields. ```json Style Object theme={null} style: { "input-focus_borderColor": "blue", "input-error_borderColor": "red", "inputErrorMessage_color": "red", } ``` You can even style the placeholder. ```json Style Object theme={null} style: { "input-placeholder_fontFamily": "Arial, sans-serif", "input-placeholder_fontSize": "14px", "input-placeholder_fontWeight": "400", "input-placeholder_color": "darkgray", } ``` Below options can be used to style the card form. ```json Style Object theme={null} style: { "card-input_gap": "0.5rem", "cardInputLogo_height": "3rem", "cardInputLogo_width": "3rem", "cardInputLogo_padding": "0.6rem", } ``` # Integrate with risk SDK Source: https://developer.tazapay.com/api-reference/javascript-sdk/integrate-with-risk-sdk This allows you to integrate with risk SDK and fetch the `session_id` For the best performance of Tazapay's Fraud Detection system, you should integrate the risk SDK into every payment process initiated by shoppers. It captures advanced signals that are leveraged in Tazapay's fraud model. These signals include: * Device Identification * Geolocation * Spoofing Attempts * Fingerprinting Data ## How it works How it works ## Integrate the risk SDK ### Set up tazapay.js ```html Production (livemode) theme={null} Checkout ``` ```html Sandbox (Testmode) theme={null} Checkout ``` **Dynamic Injection** Before injecting the SDK dynamically, please use the following event listener to determine when the script has finished loading. ```javascript theme={null} window.addEventListener('tazapaySDKReady', () => { // continue to use library }); ``` ### Initialising tazapay.js with your public key ```html HTML theme={null} const tazapay = await window.tazapay('pk_test_TYooMyTiskhfuvdEDq54NiTphI7jx'); ``` The above code creates an instance of the Tazapay object. This created object now serves as an entry-point to the rest of Tazapay’s JS SDK. > You can fetch the public key from the Tazapay dashboard. ### Retrieve the session\_id When the customer clicks to pay, publish the device data and retrieve the session\_id ```javascript JavaScript theme={null} const session_id = await tazapay.publishRiskData(); ``` > The function tazapay.publishRiskData() will create a promise when called which resolves into a session\_id string. ## Attach the session\_id to the transaction * Pass the session\_id to your server. * Pass the session\_id in the API calls to the following depending on your use case * Create Checkout * Create Payin * Confirm Payin # Integrating Client-Side Source: https://developer.tazapay.com/api-reference/javascript-sdk/integrating-client-side The integration can be completed in three steps: Include Tazapay’s JavaScript (JS) file (client-side) Fetch token for a payment session (server-side) Instantiate Tazapay’s Javascript SDK using the token (client-side) ## Step 1: Include Tazapay’s Javascript (JS) file (client-side) Add the below snippet to your application to load Tazapay’s Javascript SDK ### Sandbox (test environment) `` ### Production (live environment) `` ## Step 2: Fetching token for a session (server-side) You can fetch the token from the response of the checkout session. Please refer to [this document](/api-reference/tazapay-api/create-checkout) for creating a checkout session. ```json Checkout API response theme={null} { "status": "success", "message": "Payment Link created successfully", "data": { "token": "TqT3aDYXn6bqRuyrR6zeef15E_E7wEjWT9w_fQl_ZgHTjwwONIeOivCBV83bWHBXR9" } } ``` The token can be passed to your client side (or Front End) to instantiate Tazapay’s Javascript SDK which will allow Tazapay to know the unique transaction for which the customer is making the payment. **Your API keys are your responsibility** Since the checkout API involves using your API keys, the checkout session should always be created on your server-side. Do not share your API keys to any unauthorised parties. This includes publicly accessible areas such as GitHub, client-side code, etc. An unauthorised party can create transactions on your behalf if they get a hold of your API keys. ## Step 3: Instantiate Tazapay’s Javascript SDK using token (client-side) Once you have loaded Tazapay’s Javascript file into your client-side application using Step 1, you can instantiate Tazapay’s UI component for that particular payment using the clientToken that you have passed onto your client side (Refer Step 2).\ You can refer to the following code snippets to instantiate Tazapay’s UI component on your website/application for a particular checkout session: * Keep the division tag in your application to load the UI component. ```html Division Tag theme={null}
``` * Instantiate UI component for checkout using token and other parameters ```javascript Instantiation theme={null} const options = { clientToken: token, // Use the token obtained at step2. callbacks: { onPaymentSuccess: () => { console.log ("success") }, onPaymentFail: () => { console.log ("fail") }, onPaymentMethodSelected: () => { console.log ("onPaymentMethodSelected") }, // optional onPaymentCancel: () => { console.log ("onPaymentCancel") }, // optional }, style: {}, // optional, for customising your integration, config: { redirectionTarget: "self" // optional -> "self" or "new_window" popup: false // optional -> true or false // by default iframe will be embedded origins: 'https://your.siteOrigin,https://your.host.siteOrigin', // required only, if tazapay iframe embedded site(your site) is loaded inside an another site/iframe(your host site). }, }; window.tazapay.checkout(options); ``` ``` ``` # List to Card Embed Events Source: https://developer.tazapay.com/api-reference/javascript-sdk/list-to-card-embed-events # Managing Exchange Rates (FX) Source: https://developer.tazapay.com/api-reference/javascript-sdk/managing-exchange-rates-fx You can use the [collection methods metadata API](/api-reference/tazapay-api/collection-methods) to fetch FX rates for a transaction. You can use this FX rate to display the amount that the customer has to pay in their local currency when they select a local payment method on your website. **Never Again Lose Money due to currency (FX) volatility** Integration with Tazapay allows you to pass on all the foreign exchange risk (loss in money due to currency price fluctuations) to Tazapay and not worry about losing money due to change in currency prices. For example,\ The invoice amount for a transaction is \$100. To a customer in Brazil, Tazapay automatically converts the amount and allows the customer to pay in the more familiar Brazilian Real (BRL) in their local payment method, while ensuring that you as a merchant receive the money in your invoice currency. # Modal Styles Source: https://developer.tazapay.com/api-reference/javascript-sdk/modal-styles ## Modal Styling The Modal is used to load third-party sites for payment authorisation. This includes Card payment 3DS, Bank redirection, etc. ```json Style Object expandable theme={null} style: { "modal_padding": "1rem", "modal_zIndex": "9999", "modal_minWidth": "0%", "modal_maxWidth": "100%", "modal_minHeight": "300px", "modal_maxHeight": "100vh", "modal_background": "rgb(0 0 0 / 0.3)", "modal_backdrop": "blur(1px)", "modal-iframe_minWidth": "0%", "modal-iframe_maxWidth": "550px", "modal-iframe_minHeight": "300px", "modal-iframe_maxHeight": "100%", "modal-iframe_background": "white", "modal-iframe_borderRadius": "4px", "modal-iframe_boxshadow": "0px 10px 15px rgba(226, 232, 240, 0.32), 0px 4px 6px rgba(226, 232, 240, 0.5)", } ``` # Ready Event Source: https://developer.tazapay.com/api-reference/javascript-sdk/ready-event The ready event is triggered when the embed is fully rendered and can accept embed.focus calls. ## Method Parameters 1. `event` - mandatory\ The name of the event, in this case `ready` 2. `handler` - mandatory\ handler(event) => void is a callback function that a merchant will provide that will be called when the event is fired. When called it will be passed an event object with the following properties: | Field | Sub-field | Type | Description | | :-------- | :-------- | :----- | :------------------------------------------------------------- | | embedType | | string | The type of embed that emitted this event. In this case `card` | ## Handling an embed ready event ```javascript Javascript theme={null} cardEmbed.on('ready', function(event) { // Handle ready event }); ``` # SDK Overview Source: https://developer.tazapay.com/api-reference/javascript-sdk/sdk-overview Using Tazapay’s Javascript SDK, you can accept payments from across the world with a single secure, embeddable UI component. It is a secure component that lets you accept payments with cards and all the local payment methods in one integration. For your global business, it is the simplest way to integrate and maintain your integration. **The UI component automatically optimises for maximum checkout conversion**. As soon as Tazapay adds new payment methods, those are immediately available on the UI component as well. ## Tazapay's Javascript SDK: 1. Automatically adjusts the input fields and currency based on the payment methods and the buyer’s country. 2. Dynamically sorts payment methods based on the customer properties to increase conversion. 3. Gives you access to new payment methods without any front-end code changes as soon as Tazapay has them. 4. Allows you to customise colours, borders and fonts to match your style. # Specifying Payment Methods Source: https://developer.tazapay.com/api-reference/javascript-sdk/specifying-payment-methods You can choose to host your own payment listing screen and use Tazapay's UI component to display and collect information for particular payment methods. You can do this by [specifying the payment methods](/local-payments/overview/managing-payment-methods) while creating a checkout session. > If you choose to select only one payment method for a transaction, the UI component will not show the payment methods selection screen to your customer and will directly ask them to enter the payment details, thus minimising the number of customer clicks to complete a payment. # Style Customisation Source: https://developer.tazapay.com/api-reference/javascript-sdk/style-customisation The Tazapay SDK allows you to optionally specify your own style rules to customise the user interface of the payment page. ## Style Object Definition The style object represents CSS properties of various elements on the payment page. Use the element selector and css property name as key and css property value as value ```json Style Object theme={null} style: { "element_cssproperty": "value", "primaryButton_background": "blue", "primaryButton_borderRadius" "20px" } ``` **Auto-Generate the Style object:** You can use the tool on [this website](https://demo.tazapay.com/config) to customise the UI component and then generate the style object for your client-side code. Using the token obtained in Step 2 for the sandbox (test) environment, you can also see a [live demo](https://demo.tazapay.com/preview) of the functioning of your UI component. # Version history Source: https://developer.tazapay.com/api-reference/javascript-sdk/version-history 1. Added Dynamic Iframe Height adjustment 2. Added PopupBlocked event for blocked popups 3. Added PaymentCancel event 4. Updated default styles for popup interface 5. Added Static checkout feature 6. Added Modal support 7. Bug fixes 1. Added Dynamic Iframe Height adjustment 2. Added resizeIframe event 3. Added new style properties # Add Billing/Shipping Source: https://developer.tazapay.com/api-reference/tazapay-api/add-billingshipping post /v3/customer/{id}/{type} This endpoint adds billing/shipping details to an already existing customer object # Address Object Source: https://developer.tazapay.com/api-reference/tazapay-api/address-object ```json JSON theme={null} { "line1": "it12 3cwth", "line1": "streat 3", "city": "Vrtmore", "country": "JM", "postal_code": "00000", "state": "Vortmore" } ``` ### Object Parameters | Field | Type | Description | | :----------- | :----- | :------------------------------------ | | line1 | string | The first line of the address. | | line2 | string | The second line of the address. | | city | string | The city of the beneficiary. | | state | string | The state or province of the address. | | postal\_code | string | The postal code of the address. | | country | string | The country (ISO alpha-2 format). | # Balance Source: https://developer.tazapay.com/api-reference/tazapay-api/balance This is an object representing your real time Tazapay balance across different currencies. ## The Balance Object ```json JSON expandable theme={null} { "available": [ { "amount": "1212429", "currency": "THB" }, { "amount": "403917", "currency": "USD" }, { "amount": "-375345", "currency": "SGD" }, { "amount": "100000", "currency": "PHP" }, { "amount": "2469000", "currency": "KRW" }, { "amount": "10000000", "currency": "IDR" }, { "amount": "-36291", "currency": "EUR" }, { "amount": "1090172", "currency": "BRL" }, { "amount": "-7274", "currency": "GBP" }, { "amount": "0", "currency": "INR" } ], "object": "balance", "updated_at": "2024-09-30T10:53:03.314835Z" } ``` | Field | Sub-fields | Type | Description | | :---------- | :--------- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------- | | available | | array of json | Available balance in individual currencies | | | currency | string | Currency, uppercase, ISO-4217 standard | | | amount | integer | Amount in cents. For decimal handling of various currencies, refer to the guide [here](/api-reference/appendix/decimal-currencies) | | object | | string | String representing the object's type, Objects of the same type share the same value. It is `balance` here | | updated\_at | | timestamp | Timestamp at which the balance was last updated | # Balance Transaction Source: https://developer.tazapay.com/api-reference/tazapay-api/balance-transaction This is an object representing a transaction that affects your Tazapay balance. # Beneficiary Source: https://developer.tazapay.com/api-reference/tazapay-api/beneficiary The Tazapay Beneficiary Object represents the recipient of a payment or payout within the Tazapay platform. This object holds all relevant information about the beneficiary, including personal details, bank account information, and any other relevant metadata required for processing payments to them. ## Beneficiary ## Object Structure ```json Individual expandable theme={null} { "address": { "city": "Kingston", "country": "JM", "line1": "12 Hope Road", "postal_code": "00010", "state": "Kingston" }, "date_of_birth": "2003-04-04", "nationality": "IN", "destination": "wal_d3inm6ami8u10oqfk", "destination_details": { "type": "wallet", "wallet": { "currency": "USDC", "deposit_address": "09e53bcac0f2edxnjsui87f8bb7a9faf64789ed8", "type": "ethereum", "hosted": "no" } }, "documents": [], "email": "abc@gmail.com", "name": "Scott", "name_local": "स्कॉट", "national_identification_number": "AIDPK1234M", "party_classification": "third_party", "phone": { "calling_code": "91", "number": "9231231231" }, "registration_number": "", "tax_id": "29ABCDE1234F1Z5", "type": "individual", "status": "active" } ``` ```json Business expandable theme={null} { "address": { "city": "Vrtmore", "country": "JM", "line1": "it12 3cwth", "postal_code": "00000", "state": "Vortmore" }, "destination": "bnk_d05lmjuq59csbboqt9d0", "destination_details": { "bank": { "account_number": "DE535019045650474185", "account_type": "savings", "bank_codes": { "swift_code": "FBDEFF" }, "bank_name": "ER VOLKSBANK EG", "branch_name": "Frankfurt am Main", "country": "DE", "currency": "EUR", "firc_required": false, "iban": "DE535019045650474185", "purpose_code": "", "transfer_type": "any" }, "type": "bank" }, "documents": [], "email": "finance@gmbh-company.de", "nationality": "DE", "name": "GMBH", "name_local": "", "national_identification_number": "", "party_classification": "third_party", "phone": { "calling_code": "49", "number": "9231231231" }, "registration_number": "HRB 123456", "tax_id": "DE123456789", "type": "business", "status": "active" } ``` #### Beneficiary Details | Field | Type | Description | | :------------------------------- | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | The unique Tazapay identifier for the beneficiary. | | address | object | The address of the beneficiary. [**Address Object**](/api-reference/tazapay-api/address-object) | | date\_of\_birth | string | Date of birth of the beneficiary (for individuals). | | nationality | string | ISO 3166-1 alpha-2 country code representing the beneficiary's nationality (e.g., US, GB, IN, FR). Optional field used for enhanced compliance screening. | | destination | string | The destination identifier (if applicable). | | destination\_details | object | The details of the destination account. (**Destination Details Object**) | | documents | array | The list of documents related to the beneficiary. | | email | string | The email address of the beneficiary. | | name | string | The name of the beneficiary. Maximum 140 characters. | | name\_local | string | The local language name of the beneficiary. | | national\_identification\_number | string | The national ID number of the beneficiary. | | party\_classification | enum | Classification of the beneficiary (Possible values - `self`, `third_party`). | | phone | object | The phone details of the beneficiary. ([**Phone Object**](/api-reference/tazapay-api/phone-object)) Mandatory when beneficiary country is China (CN). Must be a valid Chinese mobile number: 11 digits, regex `^(\+86)?1[3-9]\d{9}$`. Country code `+86` is auto-prefixed. | | registration\_number | string | The registration number (for business beneficiaries). | | tax\_id | string | The tax identification number of the beneficiary. | | created\_at | string (ISO timestamp) | The date and time when the beneficiary was created. | | metadata | json | Additional key-value pairs associated with the beneficiary (optional). | | status | enum | Current status of the beneficiary. Possible values: `active`, `inactive` | ## Destination Details ### Object Structure ```json Wallet theme={null} { "type": "wallet", "wallet": { "currency": "USDC", "deposit_address": "09e53bcac0f2edxnjsui87f8bb7a9faf64789ed8", "type": "ethereum", "hosted": "yes", "vasp_name": "Binance", "vasp_website": "https://www.binance.com" } } ``` ```json Bitcoin Lightning Network theme={null} { "type": "wallet", "wallet": { "currency": "BTC", "deposit_address": "lnbc1500n1pje3xdapp...", "type": "bitcoin_lightning_network", "hosted": "no" } } ``` ```json Bank theme={null} { "bank": { "account_number": "DE535019045650474185", "account_type": "savings", "bank_codes": { "swift_code": "FBDEFF" }, "bank_name": "ER VOLKSBANK EG", "branch_name": "Frankfurt am Main", "country": "DE", "currency": "EUR", "firc_required": false, "iban": "DE535019045650474185", "purpose_code": "", "transfer_type": "any" }, "type": "bank"} ``` ```json Local Payment Network theme={null} { "local_payment_network": { "currency": "BRL", "deposit_key": "fep@gmail.com", "deposit_key_type": "email", "type": "pix_brl" }, "type": "local_payment_network" } ``` ```json Tazapay Account theme={null} { "tazapay_account": { "deposit_address": "ce4f51ue@tzp" }, "type": "tazapay_account" } ``` ## Object Parameters ### Bank | Subfield | Type | Description | | :-------------- | :------ | :---------------------------------------------------------------------- | | account\_number | string | The account number of the beneficiary's bank. | | account\_type | enum | The type of bank account. Enum value - `savings`, `checking`, `payment` | | bank\_codes | object | The bank codes (ABA / SWIFT). | | bank\_name | string | The name of the beneficiary’s bank. | | branch\_name | string | The branch name of the beneficiary’s bank. | | country | string | The country of the beneficiary’s bank. | | currency | string | The currency in which the bank account operates. | | firc\_required | boolean | Whether FIRC is required. | | purpose\_code | string | The purpose code for the bank transfer. | | transfer\_type | enum | The transfer type (values - `swift`, `local`, `any`). | | iban | string | The IBAN of the beneficiary’s bank account. | ### Wallet | Subfield | Type | Description | | :--------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | currency | string | The cryptocurrency type (e.g., `USDC`). | | deposit\_address | string | The wallet deposit address. | | type | enum | The blockchain type. \[Values: `ethereum`, `tron`, `polygon`, `solana`, `bitcoin_lightning_network`]. Use `bitcoin_lightning_network` for BTC currency only. | | hosted | enum | Indicates whether the wallet is custodial (hosted) or non-custodial (unhosted). Possible values: `yes` – The wallet is hosted by a Virtual Asset Service Provider (VASP) or exchange. `no` – The wallet is non-custodial and controlled directly by the user (e.g., MetaMask, Ledger). Mandatory if `party_classification` is 'self' and `destination_details.type` is 'wallet'. | | vasp\_name | string | The registered name of the Virtual Asset Service Provider (VASP) or exchange that hosts or manages the wallet. Mandatory if `party_classification` is 'self', `destination_details.type` is 'wallet' and `hosted` is 'yes' | | vasp\_website | string | The official website URL of the VASP or exchange that manages the wallet. Used for VASP identification and due diligence under Travel Rule requirements. Mandatory if `party_classification` is 'self', `destination_details.type` is 'wallet' and `hosted` is 'yes' | ### Local Payment Network | Subfield | Type | Description | | :----------------- | :----- | :---------------------------------------------------------------------------------------------- | | currency | string | The currency used in the local payment network. | | deposit\_key | string | The deposit key corresponding to the type of local payment network (e.g., PIX key, UPI handle). | | deposit\_key\_type | enum | Type of the deposit key. Conditionally mandatory depending on the value of type | | type | enum | The local payment network type. \[Values: `pix_brl`, `upi_inr`, `promptpay_thb`] | ### Tazapay Account | Subfield | Type | Description | | ---------------- | ------ | ------------------------------------ | | deposit\_address | string | The Tazapay account deposit address. | # Beneficiary Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/beneficiary-webhooks These are currently relevant for wallet beneficiaries (i.e. where `destination_details.type` is 'wallet'). Whenever a 1st party wallet beneficiary is created (i.e. where `party_classification` is self), beneficiaries will go through an approval flow and only when verification status of a beneficiary is succeeded, payout to it can happen **Beneficiary verification\_status specific events** | Event | Description | Default | | :--------------------------- | :--------------------------------------------------------------------- | :------ | | beneficiary.processing | Triggered when verification\_status of beneficiary is processing | off | | beneficiary.requires\_action | Triggered when verification\_status of beneficiary is requires\_action | off | | beneficiary.succeeded | Triggered when verification\_status of beneficiary is succeeded | off | | beneficiary.failed | Triggered when verification\_status of beneficiary is failed | off | **Sample Events** **beneficiary.processing** ```json JSON expandable theme={null} { "type": "beneficiary.processing", "id": "evt_d40u3boduff039n5h1t0", "object": "event", "created_at": "2025-10-29T09:43:11.83145611Z", "data": { "created_at": "2025-10-29T09:43:09.471921Z", "party_classification": "self", "registration_number": "12345", "name": "vibhui", "type": "business", "destination": "pwa_d40u3b9rcvj50sse4oe0", "id": "bnf_d40u3bbgrdjvil4n3q7g", "object": "beneficiary", "verification_status": "processing", "address": { "city": "bnds", "country": "DZ", "line1": "C-222", "line2": "123", "postal_code": "21334", "state": "fssd" }, "destination_details": { "type": "wallet", "wallet": { "currency": "USDC", "deposit_address": "ox2323", "hosted": "yes", "type": "ethereum", "vasp_name": "testing ", "vasp_website": "https://dashboard-brown.tazapay.com/beneficiary/view" } }, "phone": {}, "metadata": {}, "documents": [ { "type": "screenshot", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-beneficiary-document-qa/bnf_d40u3bbgrdjvil4n3q7g/1761730927028440823_deemed_university_AIQ.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAQKC7OY4NR3C52PE2%2F20251029%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251029T094311Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBkaDmFwLXNvdXRoZWFzdC0xIkgwRgIhAM%2BbltkEA41%2B%2F%2FUKdPZJ33XSExjrzd7um%2Bo2oJ3CPtrXAiEAyblN84DSc4r3R4KUmIqOf4o4ZG%2FAnVBAZ1176FPc3s0qiwQI0v%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARABGgwwMjE2NzUwMzQzOTUiDP3TJwq9YbcS5plRbyrfA31ENBSe4ccr15JlS1H1hg9wDbgxpXV7vEGCrdVOJgd3emv0EnYyaOl8JV9ij%2FDTXLw78oLoafB2zLfFgBi%2BO6c%2FVnOdUPdjOxHa9lBAzyfbGxZuMCJ8Y7%2B8KS0p%2B7wzA%2B2DvQTx7TQvWgbN4Ou23FPHDDOgObIJa9HIDl54vzWV8wr%2BwUYzJjh8yopcbatKj9AD2ZRPhzj%2BJYqxoZm%2Ft%2Bl1NwBHX%2BSLEKj468CT%2FuMuqVSHBPwqwwdhR39PQ%2FoXubXdA473j1LzQg%2F6o5j29NCeZ9sin3%2BQekv581ZzZUFOGPu%2Fq369YnXKjx%2F%2FYU6xJYoSsQjG72JyyXOxUVmEs5r5KeY%2BrNBcASbHLVOVQht25s5O3gjTIewzj8aMpKjLkARgsZNLQOY3ODJ6laH38RYctLjskJCd4RNGHtViyLCm2SpIuEAylmzL1xWNNVJXF50K0iX15GAy7X4sqBp7px0dQ%2F0FoF8GxdYWAd6%2BQtc10WsC4zbWOuzGUoFSJaCKMLIbrdxuKPHAVfN1AmdCFJGWXH2PmRbePCEoVS90nfPMoHKWmyFgI%2B%2BCQfkij0oRluhxpggJ1b5P6wVj4zPOubo5epAiq055CvZtHFvoTlnPibK3DiY0ImP7vA76xPZKMLq4h8gGOqQB9CGOPOnLxOGrKECNBM8hTmNc0saBmYy7oX8kdMFPTvT6%2BNo32b3%2FXvSAa79IIPVhP5T87uItyAU15qIy5VtEqfzKDN5GtW%2FYMGDg%2Fk0u8mApx1g%2BHq1tb5piA75GsNRbOH3SUrhBbW4XJ%2F03S2aUCAwLeQ57KhKP1cYW0JVaEdCAVxrdeacnKKQF7HOncyPF6z%2FunSbIgOK8337Ng1VhaUIlG0Y%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B&response-content-type=application%2Fpdf&x-id=GetObject&X-Amz-Signature=9eff71e9faf1e5e221c44c2835954c8c98835da9c8fa5de5fefe755049fcfe02" } ] } } ``` **beneficiary.requires\_action** ```json JSON expandable theme={null} { "type": "beneficiary.requires_action", "id": "evt_d40u3boduff039n5h1t0", "object": "event", "created_at": "2025-10-29T09:43:11.83145611Z", "data": { "created_at": "2025-10-29T09:43:09.471921Z", "party_classification": "self", "registration_number": "12345", "name": "vibhui", "type": "business", "destination": "pwa_d40u3b9rcvj50sse4oe0", "id": "bnf_d40u3bbgrdjvil4n3q7g", "object": "beneficiary", "verification_status": "requires_action", "address": { "city": "bnds", "country": "DZ", "line1": "C-222", "line2": "123", "postal_code": "21334", "state": "fssd" }, "destination_details": { "type": "wallet", "wallet": { "currency": "USDC", "deposit_address": "ox2323", "hosted": "yes", "type": "ethereum", "vasp_name": "testing ", "vasp_website": "https://dashboard-brown.tazapay.com/beneficiary/view" } }, "phone": {}, "metadata": {}, "documents": [ { "type": "screenshot", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-beneficiary-document-qa/bnf_d40u3bbgrdjvil4n3q7g/1761730927028440823_deemed_university_AIQ.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAQKC7OY4NR3C52PE2%2F20251029%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251029T094311Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBkaDmFwLXNvdXRoZWFzdC0xIkgwRgIhAM%2BbltkEA41%2B%2F%2FUKdPZJ33XSExjrzd7um%2Bo2oJ3CPtrXAiEAyblN84DSc4r3R4KUmIqOf4o4ZG%2FAnVBAZ1176FPc3s0qiwQI0v%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARABGgwwMjE2NzUwMzQzOTUiDP3TJwq9YbcS5plRbyrfA31ENBSe4ccr15JlS1H1hg9wDbgxpXV7vEGCrdVOJgd3emv0EnYyaOl8JV9ij%2FDTXLw78oLoafB2zLfFgBi%2BO6c%2FVnOdUPdjOxHa9lBAzyfbGxZuMCJ8Y7%2B8KS0p%2B7wzA%2B2DvQTx7TQvWgbN4Ou23FPHDDOgObIJa9HIDl54vzWV8wr%2BwUYzJjh8yopcbatKj9AD2ZRPhzj%2BJYqxoZm%2Ft%2Bl1NwBHX%2BSLEKj468CT%2FuMuqVSHBPwqwwdhR39PQ%2FoXubXdA473j1LzQg%2F6o5j29NCeZ9sin3%2BQekv581ZzZUFOGPu%2Fq369YnXKjx%2F%2FYU6xJYoSsQjG72JyyXOxUVmEs5r5KeY%2BrNBcASbHLVOVQht25s5O3gjTIewzj8aMpKjLkARgsZNLQOY3ODJ6laH38RYctLjskJCd4RNGHtViyLCm2SpIuEAylmzL1xWNNVJXF50K0iX15GAy7X4sqBp7px0dQ%2F0FoF8GxdYWAd6%2BQtc10WsC4zbWOuzGUoFSJaCKMLIbrdxuKPHAVfN1AmdCFJGWXH2PmRbePCEoVS90nfPMoHKWmyFgI%2B%2BCQfkij0oRluhxpggJ1b5P6wVj4zPOubo5epAiq055CvZtHFvoTlnPibK3DiY0ImP7vA76xPZKMLq4h8gGOqQB9CGOPOnLxOGrKECNBM8hTmNc0saBmYy7oX8kdMFPTvT6%2BNo32b3%2FXvSAa79IIPVhP5T87uItyAU15qIy5VtEqfzKDN5GtW%2FYMGDg%2Fk0u8mApx1g%2BHq1tb5piA75GsNRbOH3SUrhBbW4XJ%2F03S2aUCAwLeQ57KhKP1cYW0JVaEdCAVxrdeacnKKQF7HOncyPF6z%2FunSbIgOK8337Ng1VhaUIlG0Y%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B&response-content-type=application%2Fpdf&x-id=GetObject&X-Amz-Signature=9eff71e9faf1e5e221c44c2835954c8c98835da9c8fa5de5fefe755049fcfe02" } ] } } ``` **beneficiary.succeeded** ```json JSON expandable theme={null} { "type": "beneficiary.succeeded", "id": "evt_d40u3boduff039n5h1t0", "object": "event", "created_at": "2025-10-29T09:43:11.83145611Z", "data": { "created_at": "2025-10-29T09:43:09.471921Z", "party_classification": "self", "registration_number": "12345", "name": "vibhui", "type": "business", "destination": "pwa_d40u3b9rcvj50sse4oe0", "id": "bnf_d40u3bbgrdjvil4n3q7g", "object": "beneficiary", "verification_status": "succeeded", "address": { "city": "bnds", "country": "DZ", "line1": "C-222", "line2": "123", "postal_code": "21334", "state": "fssd" }, "destination_details": { "type": "wallet", "wallet": { "currency": "USDC", "deposit_address": "ox2323", "hosted": "yes", "type": "ethereum", "vasp_name": "testing ", "vasp_website": "https://dashboard-brown.tazapay.com/beneficiary/view" } }, "phone": {}, "metadata": {}, "documents": [ { "type": "screenshot", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-beneficiary-document-qa/bnf_d40u3bbgrdjvil4n3q7g/1761730927028440823_deemed_university_AIQ.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAQKC7OY4NR3C52PE2%2F20251029%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251029T094311Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBkaDmFwLXNvdXRoZWFzdC0xIkgwRgIhAM%2BbltkEA41%2B%2F%2FUKdPZJ33XSExjrzd7um%2Bo2oJ3CPtrXAiEAyblN84DSc4r3R4KUmIqOf4o4ZG%2FAnVBAZ1176FPc3s0qiwQI0v%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARABGgwwMjE2NzUwMzQzOTUiDP3TJwq9YbcS5plRbyrfA31ENBSe4ccr15JlS1H1hg9wDbgxpXV7vEGCrdVOJgd3emv0EnYyaOl8JV9ij%2FDTXLw78oLoafB2zLfFgBi%2BO6c%2FVnOdUPdjOxHa9lBAzyfbGxZuMCJ8Y7%2B8KS0p%2B7wzA%2B2DvQTx7TQvWgbN4Ou23FPHDDOgObIJa9HIDl54vzWV8wr%2BwUYzJjh8yopcbatKj9AD2ZRPhzj%2BJYqxoZm%2Ft%2Bl1NwBHX%2BSLEKj468CT%2FuMuqVSHBPwqwwdhR39PQ%2FoXubXdA473j1LzQg%2F6o5j29NCeZ9sin3%2BQekv581ZzZUFOGPu%2Fq369YnXKjx%2F%2FYU6xJYoSsQjG72JyyXOxUVmEs5r5KeY%2BrNBcASbHLVOVQht25s5O3gjTIewzj8aMpKjLkARgsZNLQOY3ODJ6laH38RYctLjskJCd4RNGHtViyLCm2SpIuEAylmzL1xWNNVJXF50K0iX15GAy7X4sqBp7px0dQ%2F0FoF8GxdYWAd6%2BQtc10WsC4zbWOuzGUoFSJaCKMLIbrdxuKPHAVfN1AmdCFJGWXH2PmRbePCEoVS90nfPMoHKWmyFgI%2B%2BCQfkij0oRluhxpggJ1b5P6wVj4zPOubo5epAiq055CvZtHFvoTlnPibK3DiY0ImP7vA76xPZKMLq4h8gGOqQB9CGOPOnLxOGrKECNBM8hTmNc0saBmYy7oX8kdMFPTvT6%2BNo32b3%2FXvSAa79IIPVhP5T87uItyAU15qIy5VtEqfzKDN5GtW%2FYMGDg%2Fk0u8mApx1g%2BHq1tb5piA75GsNRbOH3SUrhBbW4XJ%2F03S2aUCAwLeQ57KhKP1cYW0JVaEdCAVxrdeacnKKQF7HOncyPF6z%2FunSbIgOK8337Ng1VhaUIlG0Y%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B&response-content-type=application%2Fpdf&x-id=GetObject&X-Amz-Signature=9eff71e9faf1e5e221c44c2835954c8c98835da9c8fa5de5fefe755049fcfe02" } ] } } ``` **beneficiary.failed** ```json JSON expandable theme={null} { "type": "beneficiary.failed", "id": "evt_d40u3boduff039n5h1t0", "object": "event", "created_at": "2025-10-29T09:43:11.83145611Z", "data": { "created_at": "2025-10-29T09:43:09.471921Z", "party_classification": "self", "registration_number": "12345", "name": "vibhui", "type": "business", "destination": "pwa_d40u3b9rcvj50sse4oe0", "id": "bnf_d40u3bbgrdjvil4n3q7g", "object": "beneficiary", "verification_status": "failed", "address": { "city": "bnds", "country": "DZ", "line1": "C-222", "line2": "123", "postal_code": "21334", "state": "fssd" }, "destination_details": { "type": "wallet", "wallet": { "currency": "USDC", "deposit_address": "ox2323", "hosted": "yes", "type": "ethereum", "vasp_name": "testing ", "vasp_website": "https://dashboard-brown.tazapay.com/beneficiary/view" } }, "phone": {}, "metadata": {}, "documents": [ { "type": "screenshot", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-beneficiary-document-qa/bnf_d40u3bbgrdjvil4n3q7g/1761730927028440823_deemed_university_AIQ.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAQKC7OY4NR3C52PE2%2F20251029%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251029T094311Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBkaDmFwLXNvdXRoZWFzdC0xIkgwRgIhAM%2BbltkEA41%2B%2F%2FUKdPZJ33XSExjrzd7um%2Bo2oJ3CPtrXAiEAyblN84DSc4r3R4KUmIqOf4o4ZG%2FAnVBAZ1176FPc3s0qiwQI0v%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARABGgwwMjE2NzUwMzQzOTUiDP3TJwq9YbcS5plRbyrfA31ENBSe4ccr15JlS1H1hg9wDbgxpXV7vEGCrdVOJgd3emv0EnYyaOl8JV9ij%2FDTXLw78oLoafB2zLfFgBi%2BO6c%2FVnOdUPdjOxHa9lBAzyfbGxZuMCJ8Y7%2B8KS0p%2B7wzA%2B2DvQTx7TQvWgbN4Ou23FPHDDOgObIJa9HIDl54vzWV8wr%2BwUYzJjh8yopcbatKj9AD2ZRPhzj%2BJYqxoZm%2Ft%2Bl1NwBHX%2BSLEKj468CT%2FuMuqVSHBPwqwwdhR39PQ%2FoXubXdA473j1LzQg%2F6o5j29NCeZ9sin3%2BQekv581ZzZUFOGPu%2Fq369YnXKjx%2F%2FYU6xJYoSsQjG72JyyXOxUVmEs5r5KeY%2BrNBcASbHLVOVQht25s5O3gjTIewzj8aMpKjLkARgsZNLQOY3ODJ6laH38RYctLjskJCd4RNGHtViyLCm2SpIuEAylmzL1xWNNVJXF50K0iX15GAy7X4sqBp7px0dQ%2F0FoF8GxdYWAd6%2BQtc10WsC4zbWOuzGUoFSJaCKMLIbrdxuKPHAVfN1AmdCFJGWXH2PmRbePCEoVS90nfPMoHKWmyFgI%2B%2BCQfkij0oRluhxpggJ1b5P6wVj4zPOubo5epAiq055CvZtHFvoTlnPibK3DiY0ImP7vA76xPZKMLq4h8gGOqQB9CGOPOnLxOGrKECNBM8hTmNc0saBmYy7oX8kdMFPTvT6%2BNo32b3%2FXvSAa79IIPVhP5T87uItyAU15qIy5VtEqfzKDN5GtW%2FYMGDg%2Fk0u8mApx1g%2BHq1tb5piA75GsNRbOH3SUrhBbW4XJ%2F03S2aUCAwLeQ57KhKP1cYW0JVaEdCAVxrdeacnKKQF7HOncyPF6z%2FunSbIgOK8337Ng1VhaUIlG0Y%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B&response-content-type=application%2Fpdf&x-id=GetObject&X-Amz-Signature=9eff71e9faf1e5e221c44c2835954c8c98835da9c8fa5de5fefe755049fcfe02" ``` # Cancel Collection Account Request Source: https://developer.tazapay.com/api-reference/tazapay-api/cancel-collection-account-request post /v3/collection_account/request/{id}/cancel Cancel a pending enablement, disablement, or reenablement request attached to a collection account. # Cancel Refund Source: https://developer.tazapay.com/api-reference/tazapay-api/cancel-refund post /v3/refund/{id}/cancel This endpoint cancels an already existing refund object A request to cancel the refund can only be made if the refund object is in the `initiated` state. If the refund is in any other state, the API call will result in an error. # Cancel Payin Source: https://developer.tazapay.com/api-reference/tazapay-api/cancelling-a-payin post /v3/payin/{id}/cancel You can cancel a payin when it's in one of the following statuses - `requires_payment_method` or `requires_action`. Upon cancellation, the status changes to `cancelled`. # Checkout Source: https://developer.tazapay.com/api-reference/tazapay-api/checkout Checkout API object enables businesses to create and manage seamless online payment experiences. It lets you integrate a Tazapay-hosted payment page so that you can quickly collect cross-border payments on mobile and desktop devices. ## Object Structure ```json JSON expandable theme={null} { "id": "chk_cirsp2sl4ar024j0akj0", "object": "checkout", "invoice_currency": "USD", "amount": 100000, "amount_paid": 100000, "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "customer": "cus_afobaifawnf", "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "customer_fee_percentage" : 0, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "payment_methods": [ "paynow_sgd", "card" ], "transaction_description": "1 x trousers", "expires_at": "2023-07-21T14:01:04.576356Z", "created_at": "2023-07-19T11:44:11.722049185Z", "url": "https://checkout.tazapay.com/transaction=ajfuibfainfaonfa", "payment_status": "paid", "payment_status_description": null, "status": "expired", "payin": "chk_cirsp2sl4ar024j0akj0", "payment_attempts": [{ "id": "pat_ahbfiuahfiuaiofnioain", "object": "payment_attempt", "created_at": "2023-07-21T14:00:02.576356Z", "amount": 148000, "charge_currency": "SGD", "payin": "chk_cirsp2sl4ar024j0akj0", "payment_method_details": { "type": "paynow_sgd", "paynow_sgd": {} }, "refunded": false, "status": "succeeded", "status_description": null, "final_currency": "USD", "fx_transaction": { "initial": { "currency": "SGD", "amount": 148000 }, "final": { "currency": "USD", "amount": 100000 }, "exchange_rate": 1.48 }, "metadata": null }], "latest_payment_attempt": "pat_ahbfiuahfiuaiofnioain", "partially_paid": false, "paid_in_excess": false, "transaction_documents": [], "reference_id": "mystore_order_00001", "metadata": { "key1": "value1", "key2": "value2", "key3": "value3" }, "on_behalf_of": "ent_d3inm6ami8u10oqfm" } ``` ## Object Parameters ### Checkout | Field | Subfield | Type | Description | | :--------------------------- | :----------------------- | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | | id | | string | The Tazapay unique identifier for the checkout transaction. | | object | | string | The type of object, which is "checkout". | | invoice\_currency | | string | The currency of the invoice (e.g., USD). | | amount | | number | The total amount to be paid. | | amount\_paid | | number | The amount that has already been paid. | | customer\_details | | object | The details of the customer. | | | country | string | The country of the customer (e.g., SG for Singapore). | | | email | string | The email address of the customer. | | | name | string | The name of the customer. | | | phone | object | The phone details of the customer. ([See Phone Table](/api-reference/tazapay-api/phone-object)) | | customer | | string | The customer ID related to the checkout. | | billing\_details | | object | The billing details of the customer. | | | address | object | The address details of the billing information. ([See Address Table](/api-reference/tazapay-api/address-object)) | | | label | string | The label for the billing address (e.g., Home, Office). | | | name | string | The name of the person being billed. | | | phone | object | The phone details for billing. ([See Phone Table](/api-reference/tazapay-api/phone-object)) | | shipping\_details | | object | The shipping details of the customer. | | | address | object | The address details of the shipping information. ([See Address Table](/api-reference/tazapay-api/address-object)) | | | label | string | The label for the shipping address (e.g., Home, Office). | | | name | string | The name of the person receiving the shipment. | | | phone | object | The phone details for shipping. ( [Phone Table](/api-reference/tazapay-api/phone-object)) | | success\_url | | string | The URL where the user is redirected after a successful transaction. | | cancel\_url | | string | The URL where the user is redirected after a cancelled transaction. | | webhook\_url | | string | The URL for webhook notifications regarding this transaction. | | payment\_methods | | array | The list of payment methods available (e.g., paynow\_sgd, card). | | transaction\_description | | string | A description of the transaction (e.g., "1 x trousers"). | | expires\_at | | string (ISO Timestamp) | The expiry date and time of the checkout session. | | created\_at | | string (ISO Timestamp) | The creation date and time of the checkout session. | | url | | string | The URL for the checkout page. | | payment\_status | | string | The payment status of the transaction (e.g., paid, pending). | | payment\_status\_description | | string | Additional details on the payment status | | status | | string | The status of the checkout session (e.g., expired, active). | | payin | | string | The unique Tazapay ID of the related payin transaction. | | payment\_attempts | | array | The list of payment attempts. | | | id | string | The unique Tazapay identifier for the payment attempt. | | | object | string | The type of object, which is "payment\_attempt". | | | created\_at | string | The creation date and time of the payment attempt (ISO format). | | | amount | number | The amount attempted to be paid. | | | charge\_currency | string | The currency in which the charge was made (e.g., SGD). | | | payin | string | The ID of the related payin transaction. | | | payment\_method\_details | object | The payment method used for the attempt. (See Payment Method Details Table) | | | refunded | boolean | Indicates if the payment attempt was refunded. | | | status | string | The status of the payment attempt (e.g., succeeded, failed). | | | status\_description | string/null | A description of the status (optional). | | | final\_currency | string | The final currency after any conversion (e.g., USD). | | | fx\_transaction | object | The foreign exchange transaction details. ([See FX Transaction Table](/api-reference/tazapay-api/fx-transaction-object)) | | latest\_payment\_attempt | | string | The ID of the latest payment attempt. | | partially\_paid | | boolean | Indicates if the payment was partially paid. | | paid\_in\_excess | | boolean | Indicates if the payment was made in excess. | | transaction\_documents | | array | List of transaction-related documents (if any). | | reference\_id | | string | The reference ID for the transaction (e.g., "mystore\_order\_00001"). | | metadata | | object | Set of key-value pairs attached to the checkout object. | | customer\_fee\_percentage | | integer | Customer fees percentage incase the fees is split between customer and merchant. | | on\_behalf\_of | | string | ID of the entity on whose behalf the checkout session is created. The entity must belong to the merchant account. Format: `ent_*` | ### Payment Method Details | Field | Type | Description | | :---------- | :----- | :--------------------------------------------------------- | | type | string | The type of payment method used (e.g., paynow\_sgd, card). | | paynow\_sgd | object | Additional details specific to payment method | # Checkout Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/checkout-webhooks When a checkout is created on behalf of an entity (Checkout OBO), all webhook payloads include the `on_behalf_of` field (the entity ID) in the `data` object. This field is omitted when OBO is not used. ## Payment\_Status-specific events: These are the events created and triggered when the payment\_status of the checkout object changes. | Event | Description | Default (on/off) | | :------------ | :------------------------------------------------------ | :--------------- | | checkout.paid | payment\_status of the checkout object changes to paid. | On | ## checkout.paid ```json JSON expandable theme={null} { "type": "checkout.paid", "created_at": "2023-07-21T14:00:05.576356Z", "data": { "id": "chk_ahfafooi7ibakbfahoan", "object": "checkout", "payin": "pay_bfiuafuiafianifnao", "invoice_currency": "USD", "amount": 6700, "amount_paid": 6700, "status": "expired", "payment_status": "paid", "payment_status_description": null, "url": "https://checkout.tazapay.com/transaction=ajfuibfainfaonfa", "customer": "cus_afobaifawnf", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_methods": ["paynow_sgd", "card"], "customer_fee_percentage": 0, "transaction_description": "1 x Item", "reference_id": "55679-7657", "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "expires_at": "2023-07-21T14:01:04.576356Z", "created_at": "2023-07-19T11:44:11.722049185Z", "on_behalf_of": "ent_d3inm6ami8u10oqfm", "latest_payment_attempt": "pat_ahbfiuahfiuaiofnioain", "payment_attempts": [ { "id": "pat_ahbfiuahfiuaiofnioain", "object": "payment_attempt", "payin": "chk_ahfafooi7ibakbfahoan", "status": "succeeded", "amount": 9916, "charge_currency": "SGD", "payment_method_details": { "type": "paynow_sgd", "paynow_sgd": {} }, "fx_transaction": { "id": "fx_d209ek2fhufa9pkp5c4g", "object": "fx_transaction", "exchange_rate": 1.48, "initial": { "amount": 9916, "currency": "SGD" }, "final": { "amount": 6700, "currency": "USD" } }, "refunded": false, "status_description": null, "metadata": null, "created_at": "2023-07-21T14:00:02.576356Z" } ], "partially_paid": false, "paid_in_excess": false, "transaction_documents": [], "metadata": { "key1": "value1", "key2": "value2" } }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ## Payment\_Attempt Specific Events: These events are created and triggered when something of interest happens for a payment attempt of a checkout. | Event | Description | Default (on/off) | | :-------------------------- | :------------------------------------------------------ | :--------------- | | payment\_attempt.created | When a payment\_attempt is created for the checkout | On | | payment\_attempt.failed | When a payment\_attempt fails for the checkout | On | | payment\_attempt.processing | When the payment\_attempt moves to the processing state | Off | | payment\_attempt.succeeded | When the payment\_attempt succeeds | On | | payment\_attempt.reversed | When a payment\_attempt is reversed | On | ### payment\_attempt.created ```json JSON expandable theme={null} { "type": "payment_attempt.created", "created_at": "2023-07-21T13:59:58.000000Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "requires_action", "amount": 9916, "charge_currency": "SGD", "customer": "cus_afobaifawnf", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "issuing_country": "us", "three_d_secure": { "result": "required" } } }, "fx_transaction": null, "balance_transaction": null, "refunded": false, "reference_id": "TR000001385673188", "status_description": "", "metadata": null, "created_at": "2023-07-21T13:59:58.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### payment\_attempt.failed ```json JSON expandable theme={null} { "type": "payment_attempt.failed", "created_at": "2023-07-21T14:00:01.000000Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "failed", "amount": 9916, "charge_currency": "SGD", "customer": "cus_afobaifawnf", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_method_details": { "type": "card", "card": { "last4": "0002", "scheme": "visa", "funding": "credit", "cardholder_name": "Adam Smith", "issuing_country": "us", "checks": { "cvc_check": "fail" }, "three_d_secure": { "eci": "07", "result": "failed", "version": "2.2.0" } } }, "fx_transaction": null, "balance_transaction": null, "refunded": false, "reference_id": "TR000001385673188", "status_description": "Card declined", "metadata": null, "created_at": "2023-07-21T13:59:58.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### payment\_attempt.processing ```json JSON expandable theme={null} { "type": "payment_attempt.processing", "created_at": "2023-07-21T14:00:03.000000Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "processing", "amount": 9916, "charge_currency": "SGD", "customer": "cus_afobaifawnf", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "cardholder_name": "Adam Smith", "issuing_country": "us", "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "fx_transaction": null, "balance_transaction": null, "refunded": false, "reference_id": "TR000001385673188", "status_description": "", "metadata": null, "created_at": "2023-07-21T13:59:58.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### payment\_attempt.succeeded ```json JSON expandable theme={null} { "type": "payment_attempt.succeeded", "created_at": "2023-07-21T14:00:05.000000Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "succeeded", "amount": 9916, "charge_currency": "SGD", "customer": "cus_afobaifawnf", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "cardholder_name": "Adam Smith", "issuing_country": "us", "checks": { "cvc_check": "pass" }, "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "fx_transaction": { "id": "fx_d209ek2fhufa9pkp5c4g", "object": "fx_transaction", "exchange_rate": 1.48, "initial": { "amount": 9916, "currency": "SGD" }, "final": { "amount": 6700, "currency": "USD" } }, "balance_transaction": "btr_d679f6dqd9ne66lsngb0", "refunded": false, "reference_id": "TR000001385673188", "status_description": "", "metadata": null, "created_at": "2023-07-21T13:59:58.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### payment\_attempt.reversed ```json JSON expandable theme={null} { "type": "payment_attempt.reversed", "created_at": "2023-07-21T14:05:00.000000Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "reversed", "amount": 9916, "charge_currency": "SGD", "customer": "cus_afobaifawnf", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "cardholder_name": "Adam Smith", "issuing_country": "us", "checks": { "cvc_check": "pass" }, "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "fx_transaction": { "id": "fx_d209ek2fhufa9pkp5c4g", "object": "fx_transaction", "exchange_rate": 1.48, "initial": { "amount": 9916, "currency": "SGD" }, "final": { "amount": 6700, "currency": "USD" } }, "balance_transaction": "btr_d679f6dqd9ne66lsngb0", "refunded": false, "reference_id": "TR000001385673188", "status_description": "", "metadata": null, "created_at": "2023-07-21T13:59:58.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ## Other Events: These events are created and triggered when something interesting happens with the checkout object not related to a status change. | Event | Description | Default (on/off) | | :------------------------------- | :--------------------------------------------- | :--------------- | | checkout.created | A checkout object is created | Off | | checkout.expired | An active checkout object gets expired | On | | checkout.tax\_invoice\_generated | Triggered when Tazapay generates a tax invoice | On | ### checkout.created ```json JSON expandable theme={null} { "type": "checkout.created", "created_at": "2023-07-19T11:44:11.722049185Z", "data": { "id": "chk_ahfafooi7ibakbfahoan", "object": "checkout", "payin": "pay_aohfoahnofanofna", "invoice_currency": "USD", "amount": 6700, "amount_paid": 0, "status": "active", "payment_status": "unpaid", "payment_status_description": null, "url": "https://checkout.tazapay.com/transaction=ajfuibfainfaonfa", "customer": "cus_afobaifawnf", "on_behalf_of": "ent_d3inm6ami8u10oqfm", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_methods": ["paynow_sgd", "card"], "customer_fee_percentage": 0, "transaction_description": "1 x Item", "reference_id": "55679-7657", "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "expires_at": "2023-07-21T14:01:04.576356Z", "created_at": "2023-07-19T11:44:11.722049185Z", "latest_payment_attempt": "", "payment_attempts": [], "partially_paid": false, "paid_in_excess": false, "transaction_documents": [], "metadata": { "key1": "value1", "key2": "value2" } }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### checkout.expired ```json JSON expandable theme={null} { "type": "checkout.expired", "created_at": "2023-07-21T14:01:05.000000Z", "data": { "id": "chk_ahfafooi7ibakbfahoan", "object": "checkout", "payin": "pay_aofnoianfoanfnafn", "invoice_currency": "USD", "amount": 6700, "amount_paid": 0, "status": "expired", "payment_status": "unpaid", "payment_status_description": null, "url": "https://checkout.tazapay.com/transaction=ajfuibfainfaonfa", "customer": "cus_afobaifawnf", "on_behalf_of": "ent_d3inm6ami8u10oqfm", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_methods": ["paynow_sgd", "card"], "customer_fee_percentage": 0, "transaction_description": "1 x Item", "reference_id": "55679-7657", "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "expires_at": "2023-07-21T14:01:04.576356Z", "created_at": "2023-07-19T11:44:11.722049185Z", "latest_payment_attempt": "", "payment_attempts": [], "partially_paid": false, "paid_in_excess": false, "transaction_documents": [], "metadata": { "key1": "value1", "key2": "value2" } }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### checkout.tax\_invoice\_generated
```json JSON expandable theme={null} { "type": "checkout.tax_invoice_generated", "created_at": "2024-04-01T08:04:47.649905272Z", "data": { "id": "chk_ahfafooi7ibakbfahoan", "object": "checkout", "payin": "pay_aofnoianfoanfnafn", "invoice_currency": "USD", "amount": 6700, "amount_paid": 6700, "status": "expired", "payment_status": "paid", "payment_status_description": null, "url": "https://checkout.tazapay.com/transaction=ajfuibfainfaonfa", "customer": "cus_afobaifawnf", "customer_details": { "country": "US", "email": "singapore@tazapay.com", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Adam Smith", "phone": { "calling_code": "65", "number": "67894321" } }, "payment_methods": ["paynow_sgd", "card"], "customer_fee_percentage": 0, "transaction_description": "1 x Item", "reference_id": "55679-7657", "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "expires_at": "2023-07-21T14:01:04.576356Z", "created_at": "2023-07-19T11:44:11.722049185Z", "latest_payment_attempt": "pat_ahbfiuahfiuaiofnioain", "payment_attempts": ["pat_ahbfiuahfiuaiofnioain"], "partially_paid": false, "paid_in_excess": false, "transaction_documents": [ { "type": "tax_invoice", "url": "https://transacion.tazapay.com/invoice/download/invoiceDownload?U2FsdGVkX1/TvmUkxGLBYS/vAmk7l7wuzs2poo/pLQjjbITj8mVX0siR7guU3zA7goWnX3hLmWc2gtNdCoQv0g==" } ], "metadata": { "key1": "value1", "key2": "value2" } }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` # Collect State Machine Source: https://developer.tazapay.com/api-reference/tazapay-api/collect-state-machine How a collect moves through its possible states from creation to a terminal outcome Every collect moves through a defined set of states from the moment funds are detected to the point where they are credited (or returned). Understanding these states helps you build robust reconciliation, alerting, and customer-facing flows. *** ## Possible Paths A collect can take one of the following paths: ### Virtual Accounts and Wallets * **Incoming Payment → Succeeded** — credited directly. * **Incoming Payment → Failed** — failed directly. * **Incoming Payment → Compliance Hold → Succeeded** — placed on hold, then credited. * **Incoming Payment → Compliance Hold → Failed** — placed on hold, then rejected. ### Wallets Only * **Incoming Payment → Compliance Hold → Detected → Succeeded** — placed on hold, detected on-chain, then credited. * **Incoming Payment → Compliance Hold → Detected → Failed** — placed on hold, detected on-chain, then rejected. The `Detected` state is specific to stablecoin wallets and indicates that the blockchain transaction has been seen but is awaiting final confirmation. *** ## Diagram — Virtual Accounts Collect state machine for Virtual Accounts ## Diagram — Stablecoin Wallets `Detected` is optional — Compliance Hold can transition directly to Succeeded or Failed without going through Detected. Collect state machine for Stablecoin Wallets *** ## What Each State Means The states below describe where an individual **collect** (incoming payment) is in its lifecycle. | State | Meaning | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Compliance Hold** | The collect is paused while Tazapay completes compliance and screening checks. It can resolve to Succeeded or Failed (or to Detected first, for stablecoin wallets). | | **Detected** | *(Stablecoin wallets only)* The blockchain transaction has been seen on-chain but is awaiting final confirmation before the funds are credited. | | **Succeeded** | *(Terminal)* The funds have cleared all checks and have been credited to the balance. | | **Failed** | *(Terminal)* The collect could not be completed — for example, it was rejected during compliance — and the funds are returned. See [Reversals](/collection-accounts/incoming-payments/reversals). | *** ## See Also How compliance holds work and how to subscribe to them. What happens when a collect fails. Track state transitions via webhook events. # Collect Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/collect-webhook ## Collect status specific events | Event | Description | Default (On / Off) | | :---------------- | :------------------------------------------------------------------------------------------------------ | :----------------- | | collect.succeeded | Triggered when the status is `succeeded` | On | | collect.failed | Triggered when the status is `failed` | On | | collect.on\_hold | Triggered when the status is `on_hold` | On | | collect.detected | Triggered when the transaction has been observed on the blockchain network, prior to final confirmation | On | ## collect.succeeded ### Virtual Account ```json expandable theme={null} { "type": "collect.succeeded", "id": "evt_d30mfcg3obm733raoh7g", "object": "event", "created_at": "2025-09-10T11:57:38.761234462Z", "data": { "id": "col_d30mfargpkanp3hrmqhg", "object": "collect", "amount": 10000, "currency": "SGD", "status": "succeeded", "type": "local_bank_transfer_sgd", "payer_details": { "name": "John Doe", "payer_bank": { "account_number": "", "name": "", "address": null, "bank_codes": { "swift_code": "sdasd93e" } }, "reference_id": "", "additional_information": "" }, "destination": "cva_d3006st6pi1o9ggqkuh0", "metadata": {}, "created_at": "2025-09-10T11:57:31.967513Z", "destination_details": { "type": "virtual_account", "virtual_account": { "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore", "postal_code": "", "state": "" }, "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_codes": { "swift_code": "SLSGO2XXX" }, "bank_name": "STANDARD BANK LIMITED", "currencies": [ "SGD" ], "iban": "", "id": "cva_d2dgk0552psfuj1he0", "object": "virtual_account" } }, "holding_currency": "THB", "balance_transaction": "btr_d30mfcjgpkanp3hrmql0", "on_behalf_of": "", "tracking_details": null } } ``` ### Wallet ```json expandable theme={null} { "type": "collect.succeeded", "id": "evt_cus736u228ka51i3g0pg", "object": "event", "created_at": "2025-02-21T12:29:15.4554149Z", "data": { "id": "col_cus735e5ainf6ati9dlg", "object": "collect", "amount": 1000, "currency": "USD", "status": "succeeded", "type": "stablecoin_usdc", "payer_details": { "name": "", "payer_bank": null, "reference_id": "", "additional_information": "", "payer_wallet": { "type": "Ethereum", "deposit_address": "addrss23423423" } }, "destination": "cwa_cuivfrvkk61qlul7c8g0", "metadata": {}, "created_at": "2025-02-21T12:29:09.412049Z", "destination_details": { "type": "wallet", "wallet": { "id": "cwa_cuivfrvkk61qlul7c8g0", "object": "wallet", "type": "ethereum", "deposit_address": "wead", "currencies": [ "USD" ] } }, "holding_currency": "USD", "balance_transaction": "btr_cus736u5ainf6ati9edg", "on_behalf_of": "", "tracking_details": { "transaction_hash": "fhjkdfi9823720@#" } } } ``` ## collect.failed ### Virtual Account ```json expandable theme={null} { "type": "collect.failed", "id": "evt_cn1m86nnt3jbkq7385qd0", "object": "event", "created_at": "2024-02-07T11:06:02.538953779Z", "data": { "metadata": {}, "created_at": "2024-02-07T11:06:00.421853Z", "payer_details": { "name": "Hrithik Agarwal", "payer_bank": { "account_number":"9876542321", "name":"State Bank of Mars", "address":{ "line1":"Address Line 1", "line2":"Address Line 2", "city":"City", "state":"state", "country":"country", "postal_code":"postal code" }, "bank_codes":{ "swift_code":"SBM001" } }, "reference_id": "ref", "additional_information": "Additional Information for the transaction" }, "destination_details": { "type": "virtual_account", "virtual_account": { "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore", "postal_code": "", "state": "" }, "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_codes": { "swift_code": "SLSGO2XXX" }, "bank_name": "STANDARD BANK LIMITED", "currencies": [ "SGD" ], "iban": "", "id": "cva_d2dgk0552psfuj1he0", "object": "virtual_account" } }, "id": "col_cn1m8651ed8dn2517esg", "object": "collect", "currency": "USD", "holding_currency" : "INR", "status": "failed", "type": "wire_transfer", "destination": "cca_uafanfianknon792nfak", "amount": 100000 } } ``` ### Wallet ```json expandable theme={null} { "type": "collect.failed", "id": "evt_cus74j6228ka51i3glog", "object": "event", "created_at": "2025-02-21T12:32:12.288984183Z", "data": { "id": "col_cus74hm5ainf6atiabs0", "object": "collect", "amount": 1000, "currency": "USD", "status": "failed", "type": "stablecoin_usdt", "payer_details": { "name": "", "payer_bank": null, "reference_id": "", "additional_information": "", "payer_wallet": { "type": "Ethereum", "deposit_address": "addrss23423423" } }, "destination": "cwa_crltnagotd3175aonav0", "metadata": {}, "created_at": "2025-02-21T12:32:06.212490Z", "destination_details": { "type": "wallet", "wallet": { "id": "cwa_crltnagotd3175aonav0", "object": "wallet", "type": "ethereum", "deposit_address": "test", "currencies": [ "USD" ] } }, "holding_currency": "USD", "balance_transaction": "", "on_behalf_of": "", "tracking_details": { "transaction_hash": "fhjkdfi9823720@#" } } } ``` ## collect.on\_hold ### Virtual Account ```json expandable theme={null} { "type": "collect.on_hold", "id": "evt_cn1m86nnt3jbkq7385qd0", "object": "event", "created_at": "2024-02-07T11:06:02.538953779Z", "data": { "metadata": {}, "created_at": "2024-02-07T11:06:00.421853Z", "payer_details": { "name": "Hrithik Agarwal", "payer_bank": { "account_number":"9876542321", "name":"State Bank of Mars", "address":{ "line1":"Address Line 1", "line2":"Address Line 2", "city":"City", "state":"state", "country":"country", "postal_code":"postal code" }, "bank_codes":{ "swift_code":"SBM001" } }, "reference_id": "reffffff", "additional_information": "Additional Information for the transaction" }, "destination_details": { "type": "virtual_account", "virtual_account": { "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore", "postal_code": "", "state": "" }, "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_codes": { "swift_code": "SLSGO2XXX" }, "bank_name": "STANDARD BANK LIMITED", "currencies": [ "SGD" ], "iban": "", "id": "cva_d2dgk0552psfuj1he0", "object": "virtual_account" } }, "id": "col_cn1m8651ed8dn2517esg", "object": "collect", "currency": "USD", "holding_currency" : "INR", "status": "on_hold", "type": "wire_transfer", "destination": "cca_uafanfianknon792nfak", "amount": 100000 } } ``` ### Wallet ```json expandable theme={null} { "type": "collect.on_hold", "id": "evt_cus74bm228ka51i3gihg", "object": "event", "created_at": "2025-02-21T12:31:42.609555864Z", "data": { "id": "col_cus74a65ainf6atia7m0", "object": "collect", "amount": 1000, "currency": "USD", "status": "on_hold", "type": "stablecoin_usdc", "payer_details": { "name": "", "payer_bank": null, "reference_id": "", "additional_information": "", "payer_wallet": { "type": "Ethereum", "deposit_address": "addrss23423423" } }, "destination": "cwa_cuivfrvkk61qlul7c8g0", "metadata": {}, "created_at": "2025-02-21T12:31:36.335350Z", "destination_details": { "type": "wallet", "wallet": { "id": "cwa_cuivfrvkk61qlul7c8g0", "object": "wallet", "type": "ethereum", "deposit_address": "wead", "currencies": [ "USD" ] } }, "holding_currency": "USD", "balance_transaction": "", "on_behalf_of": "", "tracking_details": { "transaction_hash": "fhjkdfi9823720@#" } } } ``` ## collect.detected ### Wallet ```json expandable theme={null} { "type": "collect.detected", "id": "evt_cus736u228ka51i3g0pg", "object": "event", "created_at": "2025-02-21T12:29:15.4554149Z", "data": { "id": "col_cus735e5ainf6ati9dlg", "object": "collect", "amount": 1000, "currency": "USD", "status": "detected", "type": "stablecoin_usdc", "payer_details": { "name": "", "payer_bank": null, "reference_id": "", "additional_information": "", "payer_wallet": { "type": "Ethereum", "deposit_address": "addrss23423423" } }, "destination": "cwa_cuivfrvkk61qlul7c8g0", "metadata": {}, "created_at": "2025-02-21T12:29:09.412049Z", "destination_details": { "type": "wallet", "wallet": { "id": "cwa_cuivfrvkk61qlul7c8g0", "object": "wallet", "type": "ethereum", "deposit_address": "wead", "currencies": [ "USD" ] } }, "holding_currency": "USD", "balance_transaction": "", "on_behalf_of": "", "tracking_details": { "transaction_hash": "fhjkdfi9823720@#" } } } ``` # Collection Account Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/collection-account-webhooks ## Available events | Event | Description | Default (On / Off) | | :----------------------------------------- | :-------------------------------------- | :----------------- | | collection\_account.creation\_succeeded | Triggered when the status is `enabled` | On | | collection\_account.disablement\_succeeded | Triggered when the status is `disabled` | On | ## Webhook payload Every event uses the same envelope, and `data` is projected through a fixed allowlist — only the fields below are ever sent, regardless of the event. | Field | Sub-fields | Type | Description | | :---------- | :-------------------- | :-------------- | :-------------------------------------------------------------------------------------------------- | | type | | string | The event type, for example `collection_account.creation_succeeded` | | id | | string | Unique ID of the event, prefixed `evt_` | | object | | string | String representing the object's type. It is `event` here | | created\_at | | timestamp | Timestamp at which the event was created | | data | | json | The collection account, or the request driving the change — see below | | | id | string | `cva_`/`cwa_` account id on the three succeeded events, `cvar_`/`cwar_` request id on all others | | | object | string | String representing the object's type. It is always `collection_account` here | | | status | string | Account status (`enabled`/`disabled`) on the three succeeded events, request status on all others | | | on\_behalf\_of | string | ID of the entity the account is configured on behalf of, prefixed `ent_`. Empty for direct accounts | | | currencies | array of string | Currencies, uppercase, ISO-4217 standard | | | payment\_method\_type | string | Type of payment method. Sent on the three succeeded events only | | | metadata | json | Key-value pairs attached to the collection account. Sent on the three succeeded events only | | | virtual\_account | json | Bank details. Present for virtual accounts only | | | wallet | json | Wallet details. Present for wallets only | | | failure\_reason | string | Reason the request failed. Present on the `*_failed` events only | | | created\_at | timestamp | Creation timestamp of the object in `data` | | | updated\_at | timestamp | Last-updated timestamp of the object in `data` | `wallet` carries `type` and `deposit_address`. `virtual_account` carries `account_holder_name`, `account_number`, `iban`, `bank_name` and `bank_codes`, plus `bank_branch` and `bank_address` on the three succeeded events. ## Sample Events ### collection\_account.creation\_succeeded ```json expandable theme={null} { "type": "collection_account.creation_succeeded", "id": "evt_crqinqs584jmicmfjbhg", "object": "event", "created_at": "2024-09-26T09:39:55.369534811Z", "data": { "metadata": {}, "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "bank_address": { "address_line_1": "testAdd", "address_line_2": "testAdd1", "country": "United States of America" }, "bank_codes": { "ach_routing_number": "testRoutingNumber", "bank_code": "testBankCode", "bsb_code": "testBsbCode", "fedwire_routing_number": "TestFedWire", "routing_code": "testRoutingCode", "sort_code": "testSortCode", "swift_code": "testSwift" }, "bank_branch": "testBankBranch", "bank_name": "testBank", "iban": "testIban" }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:39:25.03501Z", "id": "cva_crqinja9chqqs7moi8rg", "object": "collection_account", "payment_method_type": "local_bank_transfer_cad", "status": "enabled", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ] } } ``` ### collection\_account.disablement\_succeeded ```json expandable theme={null} { "type": "collection_account.disablement_succeeded", "id": "evt_crqiom4584jmicmfjf5g", "object": "event", "created_at": "2024-09-26T09:41:44.365564104Z", "data": { "metadata": {}, "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "bank_address": { "address_line_1": "testAdd", "address_line_2": "testAdd1", "country": "United States of America" }, "bank_codes": { "ach_routing_number": "testRoutingNumber", "bank_code": "testBankCode", "bsb_code": "testBsbCode", "fedwire_routing_number": "TestFedWire", "routing_code": "testRoutingCode", "sort_code": "testSortCode", "swift_code": "testSwift" }, "bank_branch": "testBankBranch", "bank_name": "testBank", "iban": "testIban" }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:43.349835Z", "id": "cva_crqinja9chqqs7moi8rg", "object": "collection_account", "payment_method_type": "local_bank_transfer_cad", "status": "disabled", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ] } } ``` Check the collection account object parameter details here - [Global Collection Account](/api-reference/tazapay-api/global-collection-account-object) *** ## Upcoming Webhook Events The following webhook events will be available soon when Tazapay enables self-serve Collection Account creation via APIs. These events describe the **request** driving the change, not the account. In the `data` block, `id` is the request id (`cvar_`/`cwar_`) and `status` is the request status. `payment_method_type` and `metadata` are not sent on these events. Use `collection_account.creation_succeeded`, `disablement_succeeded` or `reenable_succeeded` for the account itself. | Event | Meaning | Default (On / Off) | | :------------------------------------------------ | :-------------------------------------------------------------- | :----------------- | | `collection_account.creation_under_approval_hold` | Enablement request is held pending approval | Off | | `collection_account.creation_requires_action` | Enablement request needs input from you | On | | `collection_account.creation_failed` | Enablement request failed | On | | `collection_account.creation_cancelled` | Enablement request was cancelled | On | | `collection_account.disablement_under_processing` | Disablement request has started processing | Off | | `collection_account.disablement_requires_action` | Disablement request needs input from you | On | | `collection_account.disablement_failed` | Disablement request failed | On | | `collection_account.disablement_cancelled` | Disablement request was cancelled | On | | `collection_account.reenable_under_processing` | Re-enablement request has started processing | Off | | `collection_account.reenable_failed` | Re-enablement request failed | On | | `collection_account.reenable_cancelled` | Re-enablement request was cancelled | On | | `collection_account.reenable_succeeded` | Account is enabled again (account event, `status` is `enabled`) | On | ### collection\_account.creation\_under\_approval\_hold ```json expandable theme={null} { "type": "collection_account.creation_under_approval_hold", "id": "evt_crqinqs584jmicmfjb02", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "approval_hold", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.creation\_requires\_action ```json expandable theme={null} { "type": "collection_account.creation_requires_action", "id": "evt_crqinqs584jmicmfjb03", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "requires_action", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.creation\_failed ```json expandable theme={null} { "type": "collection_account.creation_failed", "id": "evt_crqinqs584jmicmfjb04", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "failed", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "failure_reason": "Enablement request failed due to compliance check.", "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.creation\_cancelled ```json expandable theme={null} { "type": "collection_account.creation_cancelled", "id": "evt_crqinqs584jmicmfjb05", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "cancelled", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.disablement\_under\_processing ```json expandable theme={null} { "type": "collection_account.disablement_under_processing", "id": "evt_crqinqs584jmicmfjb06", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "not_initiated", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.disablement\_requires\_action ```json expandable theme={null} { "type": "collection_account.disablement_requires_action", "id": "evt_crqinqs584jmicmfjb07", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "requires_action", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.disablement\_failed ```json expandable theme={null} { "type": "collection_account.disablement_failed", "id": "evt_crqinqs584jmicmfjb08", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "failed", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "failure_reason": "Disablement request failed at the provider.", "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.disablement\_cancelled ```json expandable theme={null} { "type": "collection_account.disablement_cancelled", "id": "evt_crqinqs584jmicmfjb09", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "cancelled", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.reenable\_under\_processing ```json expandable theme={null} { "type": "collection_account.reenable_under_processing", "id": "evt_crqinqs584jmicmfjb10", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "not_initiated", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.reenable\_failed ```json expandable theme={null} { "type": "collection_account.reenable_failed", "id": "evt_crqinqs584jmicmfjb11", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "failed", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "failure_reason": "Re-enablement request failed at the provider.", "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.reenable\_cancelled ```json expandable theme={null} { "type": "collection_account.reenable_cancelled", "id": "evt_crqinqs584jmicmfjb12", "object": "event", "created_at": "2024-09-26T09:41:00.000000000Z", "data": { "id": "cvar_crqinja9chqqs7moi8rg1", "object": "collection_account", "status": "cancelled", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:00.03501Z" } } ``` ### collection\_account.reenable\_succeeded ```json expandable theme={null} { "type": "collection_account.reenable_succeeded", "id": "evt_crqinqs584jmicmfjbi2", "object": "event", "created_at": "2024-09-26T10:10:30.000000000Z", "data": { "id": "cva_crqinja9chqqs7moi8rg", "object": "collection_account", "payment_method_type": "local_bank_transfer_cad", "status": "enabled", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "currencies": [ "CAD" ], "virtual_account": { "account_holder_name": "testacc", "account_number": "testacc1234-56-1234", "iban": "testIban", "bank_name": "testBank", "bank_codes": { "ach_routing_number": "testRoutingNumber", "routing_code": "testRoutingCode", "swift_code": "testSwift" } }, "metadata": {}, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T10:10:30.03501Z" } } ``` # Collection Accounts Payment Method Type Source: https://developer.tazapay.com/api-reference/tazapay-api/collection-accounts-payment-method-type ## Virtual Account | Payment Method Type | | -------------------------- | | wire\_transfer | | local\_bank\_transfer\_cad | | local\_bank\_transfer\_krw | | local\_bank\_transfer\_sgd | | local\_bank\_transfer\_dkk | | local\_bank\_transfer\_ngn | | local\_bank\_transfer\_gbp | | local\_bank\_transfer\_eur | | local\_bank\_transfer\_usd | | local\_bank\_transfer\_php | | local\_bank\_transfer\_aud | ## Wallet | Payment Method Type | | :------------------ | | stablecoin\_usdt | | stablecoin\_usdc | # Collection Methods Fields Source: https://developer.tazapay.com/api-reference/tazapay-api/collection-methods | Field | Subfield | type | Description | | :---------------- | :----------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount | | integer | Amount in invoice currency | | customer\_country | | string | ISO 3166 standard alpha-2 code. eg: SG, IN, US, etc. | | invoice\_currency | | string | Invoice currency (in uppercase, iso-4217 standard) | | payment\_methods | | array of json | List of payment methods available for the country-currency combination | | | amount | integer | Amount in charge currency | | | banks | array of string | Banks if any for the customer to select. This is specific to a payment method | | | currency | string | Charge currency (the currency in which the customer is charged) | | | exchange\_rate | float | Exchange rate from invoice currency to charge currency | | | experience\_type | enum | `native`, `redirect_with_input`, `redirect` | | | family | enum | Family in which the payment method is characterised (`real_time_payment`, `card`, `payment_initiation_service`, `wallet`, `local_bank_transfer`, `wire_transfer`, `internet_banking`, `voucher`) | | | group | enum | `card`, `apm`, `lbt`, `wire` | | | logo\_url | array of string | Logos for the payment method | | | type | enum | Payment Method type. Unique identifier representing a payment method. This is the string that you can use to specify payment methods for a checkout / escrow session. | | | name | string | Customer display name for the payment method. Useful to call the payment method with this name on your checkout screen. | | | notification\_type | enum | Whether the payment is confirmed instantaneously with the customer in the payment flow. `synchronous` or `asynchronous` | | | transaction\_fee | integer | Fees applicable for the payment method | # Overview Source: https://developer.tazapay.com/api-reference/tazapay-api/collection-methods-api get /v3/metadata/collect This allows you to check the collection methods available for a given buyer/seller country. This also shows the supported collection methods for the invoice currency and country corridor, the banks and type of accounts that will be available. # Collect Source: https://developer.tazapay.com/api-reference/tazapay-api/collects Collects represent incoming payments to your global collection accounts. A collect is created whenever there is a credit in the collection accounts. ## Object Structure ```json Fiat Collect expandable theme={null} { "amount": 12829, "balance_transaction": "btr_u7ftrgipu69og2qj1j1pg", "created_at": "2027-08-15T03:43:46.980214Z", "currency": "SGD", "destination": "cva_d2dgk0ka772psfuj1he0", "destination_details": { "type": "virtual_account", "virtual_account": { "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore", "postal_code": "", "state": "" }, "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_codes": { "swift_code": "SLSGO2XXX" }, "bank_name": "STANDARD BANK LIMITED", "currencies": [ "SGD" ], "iban": "", "id": "cva_d2dgk0552psfuj1he0", "object": "virtual_account" } }, "holding_currency": "SGD", "id": "col_d2fapsh76og2qj0ej5g", "metadata": {}, "object": "collect", "on_behalf_of": "", "payer_details": { "additional_information": "CM Payment for Order 56", "name": "CMC COMPANY", "payer_bank": { "account_number": "1112019837840", "address": null, "bank_codes": { "swift_code": "AJUM7CHBKXXX" }, "name": "C Bank" }, "reference_id": "" }, "status": "succeeded", "tracking_details": null, "type": "wire_transfer" } } ``` ```json Crypto Collect expandable theme={null} { "status": "success", "message": "", "data": { "amount": 480000, "balance_transaction": "btr_d35s1lt7gtugq24427g", "created_at": "2025-09-18T08:20:33.090433Z", "currency": "USD", "destination": "cwa_jhrv4sad4tf55jrvp0", "destination_details": { "type": "wallet", "wallet": { "currencies": [ "USD" ], "deposit_address": "0x5gtj035ad25fnhioerfujhguri587y43894hfie2", "id": "cwa_jhrv4sad4tf55jrvp0", "object": "wallet", "type": "polygon pos" } }, "holding_currency": "USD", "id": "col_24rtg5gtugq2t3h0bg", "metadata": {}, "object": "collect", "on_behalf_of": "", "payer_details": { "additional_information": "", "name": "", "payer_bank": null, "payer_wallet": { "deposit_address": "0x48eb007deaebafmerdogn8470rjm32afa", "type": "ethereum" }, "reference_id": "" }, "status": "succeeded", "tracking_details": { "transaction_hash": "0x444b716efrg4b2a23224tf4gcedc91024f25c5bbb0530e99f09930769a" }, "type": "stablecoin_usdc" } } ``` ```json Crypto Collect (Detected) expandable theme={null} { "status": "success", "message": "", "data": { "amount": 1000, "balance_transaction": "", "created_at": "2025-02-21T12:29:09.412049Z", "currency": "USD", "destination": "cwa_cuivfrvkk61qlul7c8g0", "destination_details": { "type": "wallet", "wallet": { "currencies": [ "USD" ], "deposit_address": "wead", "id": "cwa_cuivfrvkk61qlul7c8g0", "object": "wallet", "type": "ethereum" } }, "holding_currency": "USD", "id": "col_cus735e5ainf6ati9dlg", "metadata": {}, "object": "collect", "on_behalf_of": "", "payer_details": { "additional_information": "", "name": "", "payer_bank": null, "payer_wallet": { "deposit_address": "addrss23423423", "type": "Ethereum" }, "reference_id": "" }, "status": "detected", "tracking_details": { "transaction_hash": "fhjkdfi9823720@#" }, "type": "stablecoin_usdc" } } ``` ## Object Parameters | Collect | Field | Subfield | Type | Description | | :------------------- | :---------------- | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- | | amount | | number | The total amount of the collect transaction. | | | balance\_transaction | | string | The ID of the balance transaction associated with this collect. | | | created\_at | | string (ISO timestamp) | The timestamp when the collect transaction was created. | | | currency | | string | The transaction currency (e.g., SGD). | | | destination | | string | The destination ID for the collected funds. | | | destination\_details | | object | Details about the destination account where the funds are collected. [Destination details Object.](#destination-details---virtual-account) | | | holding\_currency | | string | The holding currency used for the transaction. | | | id | | string | The unique Tazapay identifier for the collect transaction. | | | metadata | | object | Set of key-value pairs attached to the transaction. | | | object | | string | The type of object, which is "collect". | | | on\_behalf\_of | | string | The party on whose behalf the funds are collected, if applicable. | | | payer\_details | | object | Details about the payer who initiated the transfer. [Payer Details Object](#payer-details) | | | status | | string | The current status of the collect transaction. Possible values: `detected`, `on_hold`, `succeeded`, `failed`. The `detected` status applies to crypto (stablecoin wallet) collects only. | | | tracking\_details | | object | Tracking details for the transaction, if available. | | | | transaction\_hash | string | Transaction hash for a crypto transaction | | | type | | string | The type of payment method used (e.g., wire\_transfer). | | ## Destination Details - Virtual Account | Field | Type | Description | | :-------------------- | :----- | :---------------------------------------------------- | | account\_holder\_name | string | The name of the virtual account holder. | | account\_number | string | The account number for the virtual account. | | bank\_address | object | The bank’s address details. (See Bank Address Table). | | bank\_branch | string | The branch address of the bank. | | bank\_codes | object | The bank codes associated with the bank. | | bank\_name | string | The name of the bank. | | currencies | array | The list of currencies supported by the account. | | iban | string | The IBAN of the account, if applicable. | | id | string | The unique identifier of the virtual account. | | object | string | The type of object, which is "virtual\_account". | ### Bank Address | Field | Type | Description | | :--------------- | :----- | :------------------------------------------- | | address\_line\_1 | string | The first line of the bank’s address. | | address\_line\_2 | string | The second line of the bank’s address. | | city | string | The city where the bank is located. | | country | string | The country where the bank is located. | | postal\_code | string | The postal code of the bank’s address. | | state | string | The state or province of the bank’s address. | ## Destination Details - Wallet | Field | Type | Description | | :--------------- | :----- | :---------------------------------------------- | | id | string | The unique identifier of the wallet. | | type | string | The blockchain or wallet type (e.g., ethereum). | | deposit\_address | string | The deposit address of the wallet. | | currencies | array | The list of currencies supported by the wallet. | ## Payer Details | Field | Type | Description | | :---------------------- | :----- | :------------------------------------------------------------------ | | additional\_information | string | Additional information about the payment (e.g., payment reference). | | name | string | Name of the payer. | | payer\_bank | object | Payer’s bank details (See Payer Bank Table). | | reference\_id | string | Reference identifier for the payer’s transaction. | | payer\_wallet | object | Payer's wallet details (See Payer's wallet table) | ### Payer Bank | Field | Type | Description | | :-------------- | :---------- | :------------------------------------- | | account\_number | string | The payer’s bank account number. | | address | object/null | The payer’s bank address, if provided. | | bank\_codes | object | The payer’s bank codes. | | name | string | The payer’s bank name. | ### Payer Wallet | id | string | The unique identifier of the wallet. | | :--------------- | :----- | :---------------------------------------------- | | type | string | The blockchain or wallet type (e.g., ethereum). | | deposit\_address | string | The deposit address of the wallet. | # Confirm Payin Source: https://developer.tazapay.com/api-reference/tazapay-api/confirm-payin post /v3/payin/{id}/confirm Attach a payment method to the payin and create an attempt Confirms that your customer intends to pay with the provided payment method. Upon confirmation, a new payment attempt will be created. You can guide your customer through the next steps using the fields `status_description` and `latest_payment_attempt_data` # Confirm Payout Source: https://developer.tazapay.com/api-reference/tazapay-api/confirm-payout post /payout/{id}/confirm Confirm a payout by attaching source of funds # Create a lightning invoice Source: https://developer.tazapay.com/api-reference/tazapay-api/create-a-lightning-invoice post /v3/lightning_invoice_bolt11 # Create a quote Source: https://developer.tazapay.com/api-reference/tazapay-api/create-a-quote post /v3/fx/quote # Create Beneficiary Source: https://developer.tazapay.com/api-reference/tazapay-api/create-beneficiary post /v3/beneficiary This lets you create a beneficiary # Create Checkout Session Source: https://developer.tazapay.com/api-reference/tazapay-api/create-checkout post /v3/checkout This lets you create a checkout session for your customer by generating a Tazapay hosted payment page. Tazapay has a [per transaction limit](https://support.tazapay.com/is-there-a-per-transaction-limit) depending on the payment method and currency. To avoid any errors, please refer to our [FAQ](https://support.tazapay.com). # Create Collection Account Source: https://developer.tazapay.com/api-reference/tazapay-api/create-collection-account post /v3/collection_account Create a new virtual account or stablecoin wallet for collecting funds. # Create Entity Source: https://developer.tazapay.com/api-reference/tazapay-api/create-entity post /v3/entity Create a sub-entity for your account # Create Payin Source: https://developer.tazapay.com/api-reference/tazapay-api/create-payin post /v3/payin Creates a payin object. After the payin is created, provide payment method details and confirm the payin. When you use `confirm = true` during creation, you create and confirm the payin in the same API call. You MUST use the parameters in confirm API when you supply `confirm = true` # Create Payout Source: https://developer.tazapay.com/api-reference/tazapay-api/create-payout post /v3/payout This lets you initiate a payout. # Payout Quote Source: https://developer.tazapay.com/api-reference/tazapay-api/create-payout-quote post /v3/payout/quote Lock in the exact amount to be deducted for a payout. The API returns the fees along with exchange rates which will be applicable to the payout. The payout quote generated will be unique to your account. * Holding currency refers to the balance currency. This is the currency whose balance will fund the payout. In case it is not specified in the request to create a quote, the holding currency will be determined based on this priority order. * Payout Currency if the payout currency is one of the balance currencies for the account. * Primary Holding Currency * Destination Currency refers to the currency in which Tazapay will transfer funds to the beneficiary. In case it is not specified in the request to create a quote, the payout currency will be considered as the destination currency. * Payout Currency and Payout Amount are mandatory requirements to generate a quote. * The id returned in the response can be passed in the `quote` parameter in the Create Payout request to lock the exchange rates and amount to be deducted from the balance. # Create Customer Source: https://developer.tazapay.com/api-reference/tazapay-api/create-user-api post /v3/customer # Create Verification Source: https://developer.tazapay.com/api-reference/tazapay-api/create-verification post /v3/verify/payee This lets you create a payee verification. Pass either `beneficiary` (Mode A - verify an existing saved beneficiary) or inline `beneficiary_details` (Mode B). # Disable Collection Account Source: https://developer.tazapay.com/api-reference/tazapay-api/disable-collection-account put /v3/collection_account/{id} Update the alias or metadata of an existing collection account, or disable or re-enable it by supplying `action`. In **production**, disabling and re-enabling are asynchronous. The call creates a request against the account and returns immediately — the account keeps its current status until that request reaches `succeeded`. The response carries the account only: it does **not** include a `requests` array, so track progress by subscribing to the [collection account webhooks](/api-reference/tazapay-api/collection-account-webhooks) or by polling the list endpoint. In **sandbox**, disabling and re-enabling are synchronous. No request is created, no lifecycle webhook fires, `reason` is not recorded, and the returned account already reflects the new `status`. To exercise the asynchronous production flow in sandbox, drive the request states with the sandbox simulation endpoint instead. Preconditions for `action`: - `disable` — the account must currently be `enabled`. Wallet accounts cannot be disabled through this endpoint. - `reenable` — the account must currently be `disabled`, must have been disabled by you rather than by Tazapay, and must have `is_reenablement_supported` set to `true`. - Either action is rejected while another request is already in progress against the account. Disable an enabled collection account by setting `action` to `disable`. Once disabled, the account no longer accepts incoming payments. Only virtual accounts can be disabled through this endpoint. In production, disabling is asynchronous — the account keeps accepting payments until the disablement request reaches `succeeded`. The response returns the account only and does **not** include a `requests` array, so track completion by subscribing to `collection_account.disablement_succeeded` (see [Collection Account Webhooks](/api-reference/tazapay-api/collection-account-webhooks)) or by polling [List Collection Accounts](/api-reference/tazapay-api/list-collection-accounts) with `status=disabled`. In sandbox, disabling takes effect immediately: the returned account is already `disabled`, no request is created, no webhook fires, and `reason` is not recorded. An account disabled this way can be re-enabled later when `is_reenablement_supported` is `true`. Accounts disabled by Tazapay rather than by you cannot be re-enabled through the API. # Document Source: https://developer.tazapay.com/api-reference/tazapay-api/document This object allows you to attach important documents, such as invoices, delivery-proof or receipts to payin transactions. It helps keep records organized and readily accessible for both businesses and customers. ## Object ```json theme={null} { "created_at": "2023-09-13T10:22:12.711645400Z", "description": "This is a sample document", "id": "doc_ck0oql7oclf1aqlh4jdg", "metadata": null, "name": "Purchase proof", "object": "document", "reference": "esc_ck0og8noclf1aqlh4icg", "type": "tracking_url", "url": "https://drive.google.com/file/d/1q5kk5YKcCojdTYir-rONXjN7szuXE16m/view?usp=sharing" } ``` ## Parameters ### Document | Field | Type | Description | | :---------- | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | The unique Tazapay identifier for the document. | | object | string | The type of object, which is "document". | | name | string | The name of the document in case the type is others. | | description | string | A description of the document. | | url | string | The URL where the uploaded document can be accessed. | | type | enum | The type of the document \[Values - goods\_delivery\_proof, service\_delivery\_proof, tracking\_url, other]\[Values - goods\_delivery\_proof, service\_delivery\_proof, tracking\_url, other] | | reference | string | The Tazapay reference ID of the related object, such as a customer or transaction. | | created\_at | string (ISO Timestamp) | The date and time when the document was uploaded (in ISO format). | | metadata | json | Set of key value pairs associated with the document. | # Entity Source: https://developer.tazapay.com/api-reference/tazapay-api/entity ## Object Parameters ```json expandable theme={null} { "status": "success", "message": "", "data": { "approval_status": "approved", "approval_status_description": "Approved for payouts only", "approved_at": "2025-10-09T02:55:52.284767Z", "created_at": "2025-10-08T05:18:11.700575Z", "description": "", "documents": [ { "description": "Recent utility bill", "document_id": "doc_d3iv85v58tg9dlpipu2g", "file_name": "kyb_doc82697_2October2025_202590_894374483.pdf", "sub_type": "other", "tag": "", "type": "address", "updated_at": "2025-09-08T05:18:15.228195Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-test-doc" }, { "description": "Passport front", "document_id": "doc_d3iv85v58tg9dlpipu1g", "file_name": "kyb_doc10723_8October2025_docapture_manual-6.jpg", "sub_type": "passport", "tag": "identityProofTypeFrontDoc", "type": "identity", "updated_at": "2025-10-08T05:18:15.228195Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-test-doc" }, { "description": "Passport back", "document_id": "doc_d3iv85v58tg9dlpipu20", "file_name": "kyb_doc38625_8October2025_docapture_manual-6.jpg", "sub_type": "passport", "tag": "identityProofTypeBackDoc", "type": "identity", "updated_at": "2025-10-08T05:18:15.228195Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-test-doc" } ], "email": "", "id": "ent_d3iv84vs8ud68hm8dba40", "metadata": {}, "name": "James Brwon", "object": "entity", "on_behalf_of": "", "onboarding_package_url": "", "operating_address": null, "pending_documents": [], "phone": { "calling_code": "", "number": "" }, "purpose_of_use": [ "payout" ], "reference_id": "", "registration_address": { "city": "Bangkok", "country": "TH", "line1": "151/1 Richmond Boulevard, Lumpini", "line2": "", "postal_code": "10330", "state": "Pathumwan" }, "registration_date": "", "registration_number": "", "rejected_at": null, "relationship": "customer", "representatives": [ { "person_id": "psn_d3iv85v58tg9dlpipu3g", "first_name": "Msk", "last_name": "Msk", "date_of_birth": "2119-11-09", "address": { "line1": "123 Main Street", "line2": "Apt 5B", "city": "New Delhi", "state": "Delhi", "postal_code": "110018", "country": "IN" }, "nationality": "IN", "phone": { "calling_code": "91", "number": "9876543210" }, "ownership_percentage": 20, "roles": ["beneficial_owner"], "documents": [ { "description": "Passport front", "document_id": "doc_csbm1ta5grahc4olhpe0", "file_name": "kyb_doc91055_22October2024_PassportFront.png", "sub_type": "passport", "tag": "identityProofTypeFrontDoc", "type": "identity", "updated_at": "2024-10-22T08:23:21.528098Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service-qa/kyb_doc91055_22October2024_PassportFront.png" } ], "individual": { "date_of_birth": "1990-05-15", "national_identification_number": { "type": "passport", "number": "P1234567", "issuer": { "country": "SG", "state": "" }, "expiration": "2030-05-14", "country_of_citizenship": "SG" }, "nationality": "SG", "profession": { "occupation": "Software Engineer", "isco_code": "2512", "industry": "Technology", "employment_status": "employed" }, "source_of_funds": { "primary_source": "salary", "description": "" }, "employment_details": { "employer_name": "Acme Corp", "designation": "Senior Engineer" } }, "transaction_profile": { "monthly_expected_transactions_value": 10000, "monthly_expected_transaction_volume": 5, "expected_transaction_countries": ["SG", "US"], "expected_transaction_currencies": ["USD", "SGD"], "customer_risk": "low" }, "source_of_wealth": null, "statement_descriptor": "", "submit": true, "submitted_at": "2025-10-01T05:18:15.228732Z", "tax_id": "", "type": "individual", "vertical": "", "website": "" } } ``` ## Object Parameters | Field | Type | Description | | :---------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | The unique Tazapay identifier for the entity. Example: `ent_d3iv84vs8ud68hm8dba40`. | | object | string | The type of object, always `"entity"`. | | name | string | The full name of the entity or individual. Example: `James Brown`. | | type | enum | The type of entity. \[Values: `individual`, `business`]. | | relationship | string | The relationship type of the entity with Tazapay. Example: `customer`. | | approval\_status | enum | The approval status of the entity. \[Values: `approved`, `rejected`, `pending`, `resubmitted`]. | | approval\_status\_description | string | Description of the approval status. Example: `Approved for payouts only`. | | approved\_at | string | Timestamp when the entity was approved (ISO 8601). Example: `2025-10-09T02:55:52.284767Z`. | | created\_at | string | Timestamp when the entity record was created (ISO 8601). Example: `2025-10-08T05:18:11.700575Z`. | | submitted\_at | string | Timestamp when the KYB/KYC submission was made (ISO 8601). | | submit | boolean | Indicates whether the KYB submission has been completed. | | description | string | Additional notes or description for the entity. | | email | string | The email address associated with the entity. | | phone | object | Phone details of the entity. See **[Phone Object](/api-reference/tazapay-api/phone-object)**. | | registration\_number | string | The official business registration number for the entity. | | registration\_date | string | Date of business registration or incorporation (ISO 8601). | | registration\_address | object | Registered address of the entity. See **[Address Object](/api-reference/tazapay-api/address-object)**. | | operating\_address | object | Operating address of the entity. May be empty if same as registration address. See **[Address Object](/api-reference/tazapay-api/address-object)**. | | tax\_id | string | The tax identification number of the entity. | | purpose\_of\_use | array | List of purposes for which the entity is using Tazapay. Example: `["payout"]`. | | source\_of\_wealth | string | Information on the source of funds or wealth for the entity. | | statement\_descriptor | string | Custom descriptor that appears on the end customer’s statement. | | reference\_id | string | The merchant’s own reference identifier for the entity. | | vertical | string | The industry vertical or business category of the entity. | | website | string | The entity’s website URL. Example: `https://example.com`. | | individual | object | Individual-specific details. Applicable when `type` is `individual`. See **[Individual Object](#individual)** below. | | transaction\_profile | object | Expected transaction profile of the entity. See **[Transaction Profile Object](#transaction-profile)** below. | | documents | array | List of submitted documents for verification. See **Document Object**. | | pending\_documents | array | List of pending documents required for completion. | | representatives | array | List of authorised representatives of the entity. Check the [Representative](#representative) table below. | | metadata | object | Custom key-value metadata attached to the entity. | | on\_behalf\_of | string | Account ID if the entity was created on behalf of another account. | | onboarding\_package\_url | string | URL to download or view the onboarding package for the entity. | | approval\_status\_description | string | Additional notes about the approval result. | | rejected\_at | string | Timestamp when the entity was rejected, if applicable. | | relationship | string | Describes the relationship of the entity to Tazapay (e.g., `customer`, `partner`, `vendor`). | ## Individual Applicable when `type` is `individual`. | Field | Type | Description | | :------------------------------- | :----- | :------------------------------------------------------------------------------------------------------- | | date\_of\_birth | string | Date of birth in ISO 8601 format (`YYYY-MM-DD`). | | nationality | string | Two-letter ISO 3166-1 alpha-2 country code for the individual's nationality. | | gender | string | Gender of the individual. Mandatory when entity country is China (CN). Allowed values: `Male`, `Female`. | | national\_identification\_number | object | National identification document details. See sub-table below. | | profession | object | Occupation details of the individual. See sub-table below. | | source\_of\_funds | object | Source of funds information. See sub-table below. | | employment\_details | object | Employment details. See sub-table below. | ### national\_identification\_number | Field | Type | Description | | :----------------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | enum | Type of identification document. \[Values: `passport`, `driving_license`, `national_id`, `tax_id`, `residence_permit`, `other`, `asylum_registration_card`, `consular_id`, `immigration_status_document`, `indigenous_card`, `insurance_card`, `international_driving_license`, `municipal_identity_card`, `national_health_id`, `postal_identity_card`, `private_operators_card`, `professional_qualification_card`, `proof_of_citizenship`, `residence_status_document`, `service_id_card`, `social_security_card`, `visa`, `voter_id`, `work_permit`]. | | number | string | Identification document number. | | issuer | object | Issuing authority details. Contains `country` (ISO 3166-1 alpha-2) and `state` (optional). | | issue\_date | string | Issue date of the identification document in `YYYY-MM-DD` format (e.g., `2010-01-21`). Mandatory when entity country is China (CN). | | expiration | string | Expiration date of the document in `YYYY-MM-DD` format. | | country\_of\_citizenship | string | ISO 3166-1 alpha-2 country code of the individual's citizenship. | ### profession | Field | Type | Description | | :----------------- | :----- | :------------------------------------------------------------------------------------------------------------------- | | occupation | string | Occupation title. Required if `isco_code` is not provided. Max 100 characters. | | isco\_code | string | 4-digit ISCO occupation code. Required if `occupation` is not provided. | | industry | string | Industry sector. Max 100 characters. | | employment\_status | enum | Employment status. \[Values: `employed`, `self_employed`, `unemployed`, `student`, `retired`, `homemaker`, `other`]. | ### source\_of\_funds | Field | Type | Description | | :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | primary\_source | enum | Primary source of funds. \[Values: `salary`, `business_income`, `investment_income`, `inheritance`, `savings`, `gift`, `pension`, `rental_income`, `sale_of_assets`, `loan`, `scholarship`, `commission`, `royalty`, `other`]. | | description | string | Description of source of funds. Required when `primary_source` is `other`. Max 500 characters. | ### employment\_details | Field | Type | Description | | :------------- | :----- | :-------------------------------------------- | | employer\_name | string | Name of the employer. Max 200 characters. | | designation | string | Job title or designation. Max 100 characters. | ## Transaction Profile | Field | Type | Description | | :------------------------------------- | :------ | :--------------------------------------------------------------------------- | | monthly\_expected\_transactions\_value | integer | Expected total value of transactions per month (in smallest currency unit). | | monthly\_expected\_transaction\_volume | integer | Expected number of transactions per month. | | expected\_transaction\_countries | array | List of ISO 3166-1 alpha-2 country codes for expected transaction countries. | | expected\_transaction\_currencies | array | List of ISO 4217 currency codes for expected transaction currencies. | | customer\_risk | enum | Risk classification of the customer. \[Values: `low`, `medium`, `high`]. | ## Representative | Field | Type | Description | | :-------------------- | :----- | :-------------------------------------------------------------------------------------------------------- | | person\_id | string | Unique identifier for the representative. Example: `psn_d3iv85v58tg9dlpipu3g`. | | first\_name | string | The first name of the representative. | | last\_name | string | The last name of the representative. | | date\_of\_birth | string | Date of birth of the representative in ISO 8601 format. | | address | object | The address of the representative. See **[Address Object](/api-reference/tazapay-api/address-object)**. | | nationality | string | Two-letter ISO country code indicating the representative’s nationality. | | phone | object | The phone details of the representative. See **[Phone Object](/api-reference/tazapay-api/phone-object)**. | | ownership\_percentage | number | The ownership percentage the representative holds in the entity. | | roles | array | List of roles or capacities the representative serves in. Example: `["director", "beneficial_owner"]`. | | documents | array | List of documents submitted for this representative. See **Document Object**. | # Entity Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/entity-webhook
## Entity approval status specific events | Event | Description | Default | | --------------------------------- | ------------------------------------------------------------- | ------- | | `entity.approval_processing` | Triggered when the entity approval status is processing | On | | `entity.approval_requires_action` | Triggered when the entity approval status is requires\_action | On | | `entity.approval_succeeded` | Triggered when the entity approval status is succeeded | On | | `entity.approval_rejected` | Triggered when the entity approval status is rejected | On | ## Sample Events ### entity.approval\_processing ``` { "created_at": "2026-02-17T12:39:43.901330356Z", "data": { "approval_status": "submitted", "approval_status_description": "The KYB process is under review.", "created_at": "2026-01-23T11:22:27.085281Z", "documents": [ { "description": "Personal Proof of Identity", "document_id": "doc_d5pljss1bo7of7h5u5e0", "file_name": "kyb_doc34354_23January2026_1769167330074003661_Test.pdf", "sub_type": "passport", "tag": "identityProofTypeFrontDoc", "type": "identity", "updated_at": "2026-01-23T11:22:27.096517Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_d5pljss1bo7of7h5u5c0/kyb_doc34354_23January2026_1769167330074003661_Test.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=" }, { "document_id": "doc_d6a63398ddembfa2eqd0", "file_name": "kyb_doc38635_17February2026_Invoice", "sub_type": "other", "tag": "requestedDoc", "type": "other", "updated_at": "2026-02-17T12:39:41.51072Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_d5pljss1bo7of7h5u5c0/kyb_doc38635_17February2026_Invoice?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential" } ], "email": "user@example.com", "id": "ent_d5pljspj18o8ibogsjmg", "individual": { "date_of_birth": "1990-05-15", "national_identification_number": { "type": "passport", "number": "P1234567", "issuer": { "country": "SG", "state": "" }, "expiration": "2030-05-14", "country_of_citizenship": "SG" }, "nationality": "SG", "profession": { "occupation": "Software Engineer", "isco_code": "2512", "industry": "Technology", "employment_status": "employed" }, "source_of_funds": { "primary_source": "salary", "description": "" }, "employment_details": { "employer_name": "Acme Corp", "designation": "Senior Engineer" } }, "transaction_profile": { "monthly_expected_transactions_value": 10000, "monthly_expected_transaction_volume": 5, "expected_transaction_countries": ["SG", "US"], "expected_transaction_currencies": ["USD", "SGD"], "customer_risk": "low" }, "name": "JOHN WONG", "object": "entity", "pending_documents": [ "Invoice" ], "phone": {}, "purpose_of_use": [ "collect", "payout" ], "reference_id": "A1000003", "registration_address": { "city": "SG", "country": "SG", "line1": "123 Street 3/5", "line2": "", "postal_code": "123123", "state": "SG" }, "relationship": "customer", "submit": true, "submitted_at": "2026-01-23T11:22:27.101462Z", "type": "individual" }, "id": "evt_d6a633obm14biavhciig", "object": "event", "type": "entity.approval_processing" } ``` ### entity.approval\_requires\_action ``` { "created_at": "2026-02-18T06:47:36.485931431Z", "data": { "approval_status": "requires_action", "approval_status_description": "Upload the doc", "created_at": "2026-02-17T05:52:28.992314Z", "documents": [ { "document_id": "doc_d6a0udrgbjuth19tnvsg", "file_name": "kyb_doc51787_17February2026_Invoice", "sub_type": "other", "tag": "additionalDoc", "type": "other", "updated_at": "2026-02-17T06:48:23.509145Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_d6a04798ddembfa2e50g/kyb_doc51787_17February2026_Invoice?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAUGJYD3OSYWCDJB4N%2F20260218%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20260218T064736Z&X-Amz-Expires=3600&X-Amz-Security-Token=" }, { "document_id": "doc_d6a64vh8ddembfa2eqm0", "file_name": "kyb_doc51241_17February2026_Invoice", "sub_type": "other", "tag": "requestedDoc", "type": "other", "updated_at": "2026-02-17T12:43:42.642691Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_d6a04798ddembfa2e50g/kyb_doc51241_17February2026_Invoice?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAUGJYD3OSYWCDJB4N%2F20260218%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20260218T064736Z&X-Amz-Expires=3600&X-Amz-Security-Token=" } ], "email": "", "id": "ent_d6a0475jd0fvsnsige9g", "name": "Dhanutestentity", "object": "entity", "operating_address": { "city": "Chennai", "country": "AO", "line1": "124", "line2": "134", "postal_code": "621216", "state": "3243" }, "pending_documents": [ "Invoice" ], "purpose_of_use": [ "payout" ], "reference_id": "ent_d6a0475jd0fvsnsige9g", "registration_address": { "city": "Chennai", "country": "AO", "line1": "124", "line2": "134", "postal_code": "621216", "state": "3243" }, "registration_number": "1324345", "relationship": "customer", "submit": true, "submitted_at": "2026-02-17T05:52:32.236083Z", "type": "company", "vertical": "Digital Products-Apps, eBooks, Blogs & Games" }, "id": "evt_d6am120bm14biavobg90", "object": "event", "type": "entity.approval_requires_action" } ``` ### entity.approval\_succeeded ``` { "created_at": "2026-02-18T10:24:09.274176008Z", "data": { "approval_status": "approved", "approval_status_description": "Approved", "approved_at": "2026-02-18T10:24:06.791763Z", "created_at": "2026-02-17T05:52:28.992314Z", "documents": [ { "document_id": "doc_d6a0udrgbjuth19tnvsg", "file_name": "kyb_doc51787_17February2026_Invoice", "sub_type": "other", "tag": "additionalDoc", "type": "other", "updated_at": "2026-02-17T06:48:23.509145Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_d6a04798ddembfa2e50g/kyb_doc51787_17February2026_Invoice?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAUGJYD3OSSZXQQ2WF%2F20260218%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20260218T102409Z&X-Amz-Expires=3600&X-Amz-Security-Token" }, { "document_id": "doc_d6a64vh8ddembfa2eqm0", "file_name": "kyb_doc51241_17February2026_Invoice", "sub_type": "other", "tag": "requestedDoc", "type": "other", "updated_at": "2026-02-18T10:24:06.791763Z", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_d6a04798ddembfa2e50g/kyb_doc51241_17February2026_Invoice?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIAUGJYD3OSSZXQQ2WF%2F20260218%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20260218T102409Z&X-Amz-Expires=3600&X-Amz-Security-Token" } ], "email": "", "id": "ent_d6a0475jd0fvsnsige9g", "name": "Dhanutestentity", "object": "entity", "operating_address": { "city": "Chennai", "country": "AO", "line1": "124", "line2": "134", "postal_code": "621216", "state": "3243" }, "pending_documents": [ "Invoice" ], "purpose_of_use": [ "payout" ], "reference_id": "ent_d6a0475jd0fvsnsige9g", "registration_address": { "city": "Chennai", "country": "AO", "line1": "124", "line2": "134", "postal_code": "621216", "state": "3243" }, "registration_number": "1324345", "relationship": "customer", "submit": true, "submitted_at": "2026-02-17T05:52:32.236083Z", "type": "company", "vertical": "Digital Products-Apps, eBooks, Blogs & Games" }, "id": "evt_d6ap6i8837kbtle7pk2g", "object": "event", "type": "entity.approval_succeeded" } ``` ### entity.approval\_rejected
``` { "created_at": "2026-02-06T08:34:15.760954054Z", "data": { "approval_status": "rejected", "approval_status_description": "Rejected as documents are invalid", "created_at": "2026-01-23T11:33:32.042822Z", "documents": [ { "description": "Personal Proof of Identity", "document_id": "doc_d5plp341bo7of7h5u6a0", "file_name": "kyb_doc61151_23January2026_1test_.pdf", "sub_type": "passport", "tag": "identityProofTypeFrontDoc", "type": "identity", "updated_at": "2026-01-23T11:33:32.054037Z" } ], "email": "user@example.com", "id": "ent_d5plp31j18o8ibogtc8g", "individual": { "date_of_birth": "1990-05-15", "national_identification_number": { "type": "passport", "number": "P1234567", "issuer": { "country": "SG", "state": "" }, "expiration": "2030-05-14", "country_of_citizenship": "SG" }, "nationality": "SG", "profession": { "occupation": "Software Engineer", "isco_code": "2512", "industry": "Technology", "employment_status": "employed" }, "source_of_funds": { "primary_source": "salary", "description": "" }, "employment_details": { "employer_name": "Acme Corp", "designation": "Senior Engineer" } }, "transaction_profile": { "monthly_expected_transactions_value": 10000, "monthly_expected_transaction_volume": 5, "expected_transaction_countries": ["SG", "US"], "expected_transaction_currencies": ["USD", "SGD"], "customer_risk": "low" }, "name": "JOHN WONG", "object": "entity", "phone": {}, "purpose_of_use": [ "collect", "payout" ], "reference_id": "A1000003", "registration_address": { "city": "SG", "country": "SG", "line1": "123 Street 3/5", "line2": "", "postal_code": "123123", "state": "SG" }, "relationship": "customer", "submit": true, "submitted_at": "2026-01-23T11:33:32.060329Z", "type": "individual" }, "id": "evt_d62qf1rf3su1i69ash4g", "object": "event", "type": "entity.approval_rejected" } ``` # Fetch a lightning invoice Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-a-lightning-invoice get /v3/lightning_invoice_bolt11/{id} # Fetch Adjustments Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-adjustments get /v3/settlement/{id}/transactions/adjustment # Fetch Balance Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-balance get /v3/balance Provides real-time access to available funds across multiple currenices # Fetch Balance Transaction Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-balance-transaction get /v3/balance_transaction/{id} Provides real-time, detailed insights into individual balance movements, including charges, currency conversions, and adjustments, allowing you to track all credits and debits across multiple currencies # Fetch Beneficiary Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-beneficiary get /v3/beneficiary/{id} This lets you fetch an existing beneficiary # Fetch Collect Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-collect get /collect/{id} Get details of a collect object # Fetch Collects Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-collects get /v3/settlement/{id}/transactions/collect # Fetch Entity Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-entity get /v3/entity/{id} # Fetch Exchange Rates Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-exchange-rates get /v3/fx/payout Retrieve exchange rate between currency pairs # Fetch External Account Details Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-external-account-details get /v3/metadata/external_account_details Fetch Account Details using the tax ID # Fetch Payins Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-payins get /v3/settlement/{id}/transactions/payin This endpoint enables you to fetch the list of payins associated with a settlement # Fetch Payment Attempt Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-payment-attempt get /v3/payment_attempt/{id} Refers to each attempt by the customer to pay using a particular payment method # Fetch payout Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-payout get /v3/payout/{id} This lets you fetch the details of an existing payout # Fetch Payouts Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-payouts get /v3/settlement/{id}/transactions/payout # Fetch Quote Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-quote get /v3/fx/quote/{id} # Fetch Refunds Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-refunds get /v3/settlement/{id}/transactions/refund # Fetch Verification Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-verification get /v3/verification/payee/{id} This lets you fetch the details of a verification by its ID. # Fetch Verification Metadata Source: https://developer.tazapay.com/api-reference/tazapay-api/fetch-verification-metadata get /v3/verification/payee/metadata This lets you fetch verification capabilities and required fields for a given corridor. Useful when integrating a new corridor or if you're unsure of the requirements. # Fetch Payin Source: https://developer.tazapay.com/api-reference/tazapay-api/fetching-a-payin get /v3/payin/{id} # Funding a Payout Source: https://developer.tazapay.com/api-reference/tazapay-api/fund-payout post /v3/payout/{id}/fund Fund a payout which is in requires_funding # FX Transaction Object Source: https://developer.tazapay.com/api-reference/tazapay-api/fx-transaction-object ## Object Structure ```json FX Transaction theme={null} { "exchange_rate": 1, "final": { "amount": 10000000, "currency": "USD" }, "id": "fx_d35tfigo4p2dt2hh0", "initial": { "amount": 10000000, "currency": "USD" }, "object": "fx_transaction" }, ``` ## Object Parameters | Field | Type | Description | | :--------------- | :----- | :--------------------------------------- | | exchange\_rate | number | The exchange rate applied for FX. | | final.amount | number | The final amount after FX conversion. | | final.currency | string | The currency of the final amount. | | initial.amount | number | The initial amount before FX conversion. | | initial.currency | string | The currency of the initial amount. | | id | string | The FX transaction ID. | # Fetch Checkout Source: https://developer.tazapay.com/api-reference/tazapay-api/get-checkout-session get /v3/checkout/{id} This lets you fetch the details of the checkout session Tazapay has a [per transaction limit](https://support.tazapay.com/is-there-a-per-transaction-limit) depending on the payment method and currency. To avoid any errors, please refer to our FAQ. # Get Collection Account Source: https://developer.tazapay.com/api-reference/tazapay-api/get-collection-account get /v3/collection_account/{id} Retrieves the details of an existing collection account by its unique ID. # Fetch Customer Details Source: https://developer.tazapay.com/api-reference/tazapay-api/get-user-by-email-api get /v3/customer/{id} This endpoint fetches the details of an already existing customer Allows you to look up details of existing customers on Tazapay's database with the customer id. # Update Customer Source: https://developer.tazapay.com/api-reference/tazapay-api/get-user-by-id-api put /v3/customer/ This endpoint updates an already existing customer object Allows you to look up details of existing users on Tazapay's database with their Tazapay account UUID. # Collection Account Source: https://developer.tazapay.com/api-reference/tazapay-api/global-collection-account-object Tazapay provides you with global collection accounts which you can share with your customers to receive payments in local currencies or using the SWIFT network. You can then withdraw the collected funds from the global collection accounts into the currency and bank account of your choice. ## Object Structure ### Virtual account ```json expandable theme={null} { "id": "cva_crqinja9chqqs7moi8rg", "object": "virtual_account", "type": "virtual_account", "status": "enabled", "status_description": "", "payment_method_type": "local_bank_transfer_cad", "country": "CA", "ftn": "EFT", "currencies": [ "CAD" ], "alias": "CAD Collection Account", "description": "This account is used for CAD collections", "on_behalf_of": "ent_d72h4h5hq6qriqd392e0", "is_reenablement_supported": true, "is_temporarily_disabled": false, "virtual_account": { "account_holder_name": "John Doe", "account_number": "1234567890-56-7890", "iban": "", "bank_name": "Bank of America", "bank_branch": "Downtown Branch", "bank_address": { "address_line_1": "123 Main Street", "address_line_2": "Suite 500", "city": "Toronto", "state": "ON", "country": "United States of America", "postal_code": "M5H 2N2" }, "bank_codes": { "ach_routing_number": "021000021", "bank_code": "001", "bsb_code": "033-001", "fedwire_routing_number": "021000021", "routing_code": "021000021", "sort_code": "12-34-56", "swift_code": "BOFAUS3N" } }, "fee_details": { "one_time_setup_fee": 5000, "maintenance_fee": 2000, "maintenance_fee_frequency": "yearly" }, "balance_transaction": "btr_d1jp5v0f3uhv3dumbkhg", "metadata": {}, "created_at": "2025-06-17 10:39:25.03501 +0000 UTC", "updated_at": "2025-06-17 10:41:43.349835 +0000 UTC" } ``` ### Wallet ```json expandable theme={null} { "id": "cwa_crltnagotd3175aonav0", "object": "wallet", "type": "wallet", "status": "enabled", "status_description": "", "payment_method_type": "stablecoin_usdt", "currencies": [ "USD" ], "alias": "USDT Wallet", "description": "USDT Ethereum wallet for collections", "is_reenablement_supported": false, "is_temporarily_disabled": false, "wallet": { "type": "Ethereum", "deposit_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B", }, "metadata": {}, "created_at": "2024-09-19 08:07:06.576777 +0000 UTC", "updated_at": "2024-09-19 08:07:06.576777 +0000 UTC" } ``` ## Object Parameters ### collection\_account | Parameter | Type | Description | | :-------------------------- | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Unique identifier (ID) associated with the collection\_account. 24 characters, prefixed `cva_` (virtual account), `cwa_` (wallet) or `cta_` (Tazapay account) | | object | enum | `virtual_account`, `wallet` or `tazapay_account`. Mirrors `type` | | type | enum | Type of collection account: `virtual_account`, `wallet` or `tazapay_account` | | status | enum | Current status of the collection account — `enabled` or `disabled`. A newly created account is always `disabled` until its enablement request reaches `succeeded` | | status\_description | string | Description of the current status, for example the disablement reason | | payment\_method\_type | enum | Payment Method Type used for the account. Refer [List](/api-reference/tazapay-api/collection-accounts-payment-method-type) | | country | string | Country in which the account is opened. Empty for wallets | | ftn | string | Fund transfer network the account settles on. Present for virtual accounts on a local rail | | currencies | array of string | List of supported currencies the collection account can receive funds in (ISO 4217) | | alias | string | Nickname you gave the account | | description | string | Usecase description for this account | | on\_behalf\_of | string | ID of the entity this account is configured on behalf of, prefixed `ent_`. Empty for direct accounts | | is\_reenablement\_supported | boolean | Whether the account can be re-enabled after being disabled | | is\_temporarily\_disabled | boolean | Whether the account is temporarily disabled and cannot currently receive funds | | virtual\_account/wallet | object | Consists of all the bank account/wallet details. Please check [virtual\_account](#virtual_account), [wallet](#wallet) | | requests | array of object | Enablement, disablement and re-enablement requests attached to this account. Returned on the retrieve and list responses only — **not** on the update response | | documents | array of object | Supporting documents attached to this account's requests | | activity\_timeline | array of object | Audit trail of status changes across this account's requests | | fee\_details | object | Pricing resolved for this account. Please check [fee\_details](#fee_details) | | balance\_transaction | string | ID of the balance transaction linked to this collection account | | metadata | json | Set of key-value pairs attached to the collection\_account object | | created\_at | string | Collection Account creation timestamp. See [Timestamp formats](#timestamp-formats) | | updated\_at | string | Collection account last updated timestamp. See [Timestamp formats](#timestamp-formats) | ### virtual\_account | Parameter | Type | Description | | :-------------------- | :----- | :------------------------------------------ | | account\_holder\_name | string | Name of the account holder | | account\_number | string | Account number of the collection account | | bank\_address | json | Bank address of the collection account bank | | bank\_codes | json | Bank codes of the collection account bank | | bank\_branch | string | Bank branch of the collection account bank | | bank\_name | string | Bank name of the collection account bank | | iban | string | IBAN of the collection account bank | ### wallet | Parameter | Type | Description | | :-------------- | :----- | :------------------------ | | type | string | Type of wallet | | deposit address | string | Deposit address of wallet | # Lightning Invoice Source: https://developer.tazapay.com/api-reference/tazapay-api/lightning-invoice This repesents a bolt11 standard invoice on the bitcoin lightning network ## Object structure ```json JSON expandable theme={null} { "id": "l11_abc123xyz", "object": "lightning_invoice_bolt11", "amount": 12345600, "d_tag_memo": "Payment for order #7890", "h_tag_memo": "f2ca1bb6c7e907d06dafe4687e579fce76c70fd6", "collect": "col_98765", "expiry_interval": 3600, "metadata": { "order_id": "7890", "customer_id": "cust_456" }, "status": "active", "payment_status": "unpaid", "created_at": "2025-09-28T08:15:30Z", "updated_at": "2025-09-28T08:20:45Z" } ``` ## Object Parameters | Field | type | Description | | :--------------- | :-------- | :--------------------------------------------------------------------------------------------------------------- | | id | string | Unique ID of the object | | object | enum | This is lightning\_invoice\_bolt11 here | | amount | integer | Amount in BTC. The precision is 8 decimal places | | d\_tag\_memo | string | This will be included in the d-tag. If both d\_tag\_memo and h\_tag\_memo are provided, only h\_tag will be used | | h\_tag\_memo | string | SHA-256 of the d\_tag\_memo. If both d\_tag\_memo and h\_tag\_memo are provided, only h\_tag\_memo will be used | | expiry\_interval | integer | The expiry of the invoice in seconds. Default value is 3600 (1 hour). | | collect | string | Collect ID which is created when the invoice gets funded | | status | enum | active, expired | | payment\_status | enum | paid, unpaid | | created\_at | timestamp | Timestamp at which this object was created | | updated\_at | timestamp | Timestamp at which this object was last updated | | metadata | json | Set of key-value pairs attached to the object | # List Balance Transactions Source: https://developer.tazapay.com/api-reference/tazapay-api/list-balance-transactions get /v3/balance_transaction Returns a list of transactions that have contributed to the Tazapay account balance. The transactions are returned in sorted order, with the most recent transactions appearing first. # List banks Source: https://developer.tazapay.com/api-reference/tazapay-api/list-banks get /v3/payout/bank search and retrieve bank entities from global bank directory [GET] # List Collection Accounts Source: https://developer.tazapay.com/api-reference/tazapay-api/list-collection-accounts get /v3/collection_account Returns a paginated list of collection accounts. # List entity Source: https://developer.tazapay.com/api-reference/tazapay-api/list-entity get /v3/entity # List Verifications Source: https://developer.tazapay.com/api-reference/tazapay-api/list-verifications get /v3/mpdashboard/verifications This lets you retrieve a paginated list of payee verifications for your account. Dashboard-session authenticated (Bearer), unlike the Basic-auth verification endpoints above. Pagination is page-based (`page_size` + `current_page`), not cursor-based. # Overview Source: https://developer.tazapay.com/api-reference/tazapay-api/overview Verify payee bank accounts before initiating payouts Sending money to the wrong account is costly for your business and your payees. Tazamatch lets you confirm that a bank account exists and that the account holder's name matches your intended recipient, before a payout is ever initiated. By verifying payees upfront, you can reduce failed payouts, catch potential fraud early, and build trust with your recipients without adding friction to your payout flow. Verification is non-blocking, meaning your existing payout operations continue uninterrupted. Tazapay normalises verification results across corridors into a consistent response, so your integration stays simple regardless of where you're paying. ## The Verification Object ```json JSON expandable theme={null} { "id": "pyv_xxxx", "object": "verification", "verification_status": "valid", "status_description": "", "beneficiary": "bnf_xxxx", "beneficiary_details": { "type": "individual", "email": "", "tax_id": "", "address": { "city": "Mumbai", "country": "IN", "line1": "123 Main Street", "line2": "", "postal_code": "400001", "state": "Maharashtra" }, "phone": { "calling_code": "+91", "number": "9876543210" }, "destination_details": { "type": "bank", "bank": { "account_number": "9876543210", "account_type": "savings", "bank_codes": { "ifsc_code": "HDFC0001234" }, "bank_name": "HDFC Bank", "country": "IN", "currency": "INR" } } }, "verified_information": { "name_match_details": { "type": "continuous", "value": 0.97, "summary": "strong_match", "translated_name": "", "corrected_name": "" }, "account_exists": true, "beneficiary_type": "individual", "transaction_activity_details": null, "additional_information": null }, "balance_transaction": { "holding_currency": "USD", "balance_impact": -10, "balance_transaction_id": "txn_xxxx" }, "metadata": null, "created_at": "2026-04-07T10:00:00Z", "updated_at": "2026-04-07T10:00:05Z" } ``` | Field | Sub-fields | Type | Description | | :-------------------- | :----------------------------- | :-------- | :-------------------------------------------------------------------------------------------- | | id | | string | Unique ID of the verification object. Prefix `pyv_` | | object | | string | String representing the object's type. It is `verification` here | | verification\_status | | string | Outcome of the verification. One of `pending`, `valid`, `invalid`, `not_supported`, `failed` | | status\_description | | string | Additional context on the verification status, when available | | beneficiary | | string | ID of the saved beneficiary that was verified (`bnf_xxxx`), if Mode A was used | | beneficiary\_details | | json | Payee details that were verified, either resolved from the saved beneficiary or passed inline | | | type | string | Type of beneficiary entity: `individual` or `business` | | | email | string | Email address of the beneficiary | | | tax\_id | string | Tax identification number of the beneficiary | | | address | json | Address of the beneficiary | | | phone | json | Phone number of the beneficiary | | | destination\_details | json | Destination account details that were verified, including bank and account identifiers | | verified\_information | | json | Results returned by the verification provider. `null` until the verification completes | | | name\_match\_details | json | Details of the name-match check between the beneficiary's name and the account holder's name | | | account\_exists | boolean | Whether the destination account exists | | | beneficiary\_type | string | Beneficiary type as reported by the verification provider | | | transaction\_activity\_details | json | Transaction activity details for the account, when supported by the corridor | | | additional\_information | string | Extra context returned by the verification provider, when available | | balance\_transaction | | json | The balance transaction created for the verification fee | | | holding\_currency | string | Currency the verification fee was charged in | | | balance\_impact | integer | Amount deducted from your balance for this verification, in cents | | | balance\_transaction\_id | string | ID of the balance transaction (`txn_xxxx`) | | metadata | | json | Key-value data attached to the verification, echoed back from the request | | created\_at | | timestamp | Timestamp at which the verification was created | | updated\_at | | timestamp | Timestamp at which the verification was last updated | ## Next Steps Check coverage and required fields for a corridor Submit a verification request Get notified when a verification completes # Payin Source: https://developer.tazapay.com/api-reference/tazapay-api/payin Payin allows businesses to collect payments from customers globally. It facilitates cross-border payments by enabling payments through various methods such as credit/debit cards, local payment methods, bank transfers, or e-wallets, depending on the supported payment options in the region. A payin refers to the process through which a merchant collects payments through Tazapay’s cross-border payment platform. This can be done through various methods such as credit/debit cards, local payment methods, bank transfers, or e-wallets, depending on the supported payment options in the region. ## Object Structure ```json JSON theme={null} { "amount": 100, "amount_paid": 0, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "cancel_url": "https://mystore.com/try_again", "cancelled_at": null, "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=", "confirm": false, "created_at": "2024-10-07T07:10:21.894488Z", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "holding_currency": "INR", "id": "pay_cs1oina7a5ng2a3ng12g", "invoice_currency": "INR", "items": [], "latest_payment_attempt": "", "latest_payment_attempt_data": null, "metadata": { "key1": "value1", "key2": "value2", "key3": "value3" }, "object": "payin", "paid_in_excess": false, "partially_paid": false, "payment_attempts": [], "payment_method_details": { "paynow_sgd": {}, "type": "paynow_sgd" }, "reference_id": "123", "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "statement_descriptor": "tzp*string", "status": "requires_payment_method", "status_description": "", "reversed_at": null, "risk_check": null, "success_url": "https://mystore.com/success_page", "transaction_data": [], "transaction_description": "test", "transaction_documents": [], "webhook_url": "https://mystore.com/internal/webhook", "on_behalf_of": "ent_d3inm6ami8u10oqfm" } ``` ## Object Parameters ### Payin | Field | Subfield | Type | Description | | :----------------------------- | :---------- | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount | | number | The total amount of the payin transaction. | | amount\_paid | | number | The amount that has already been paid. | | billing\_details | | object | The billing information for the transaction. | | | address | object | The address associated with the billing details. [Address Object](/api-reference/tazapay-api/address-object) | | | label | string | A label for the billing address (e.g., Home, Office). | | | name | string | The name associated with the billing details. | | | phone | object | The phone details associated with the billing address. (See Phone Table). | | cancel\_url | | string | The URL to redirect the user to if the transaction is canceled. | | cancelled\_at | | string(ISO timestamp) | The timestamp when the transaction was canceled, if applicable. | | client\_token | | string | The client token associated with the payin. | | confirm | | boolean | Indicates if the transaction is confirmed. | | created\_at | | string (ISO timestamp) | The timestamp when the transaction was created. | | customer | | string | The unique identifier for the customer. | | customer\_details | | object | The customer details related to the transaction. | | | country | string | The country of the customer. | | | email | string | The email address of the customer. | | | name | string | The name of the customer. | | | phone | object | The phone details of the customer. [Phone Object.](/api-reference/tazapay-api/phone-object) | | holding\_currency | | string | The holding currency used for the transaction (e.g., INR). | | id | | string | The unique Tazapay identifier for the payin transaction. | | invoice\_currency | | string | The invoice currency for the transaction. | | items | | array | The list of items related to the transaction. | | latest\_payment\_attempt | | string | The Tazapay ID of the latest payment attempt. | | latest\_payment\_attempt\_data | | object/null | Data related to the latest payment attempt, if available. | | metadata | | object | Set of key-value pairs attached to the transaction. | | object | | string | The type of object, which is "payin". | | paid\_in\_excess | | boolean | Indicates if the payment was made in excess. | | partially\_paid | | boolean | Indicates if the payment was partially paid. | | payment\_attempts | | array | The list of payment attempts for this transaction. | | payment\_method\_details | | object | The details of the payment method used. | | | paynow\_sgd | object | Details of the paynow\_sgd payment method | | | type | string | The type of payment method used (e.g., paynow\_sgd). | | reference\_id | | string | The reference ID for the transaction. | | shipping\_details | | object | Shipping information for the transaction. | | | address | object | The address associated with the shipping details. [Address object](/api-reference/tazapay-api/address-object) | | | label | string | A label for the shipping address (e.g., Home, Office). | | | name | string | The name associated with the shipping details. | | | phone | object | The phone details associated with the shipping address. [Phone Object](/api-reference/tazapay-api/phone-object) | | statement\_descriptor | | string | The descriptor to appear on the customer’s statement. | | status | | string | The current status of the transaction. Possible values: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `cancelled`, `reversed`. | | status\_description | | string | A description of the transaction status, if available. | | reversed\_at | | string (ISO timestamp) | The timestamp when the payin was reversed. `null` unless `status` is `reversed`. | | risk\_check | | object / null | Result of the automated payer name verification check. `null` when no name match check was performed. | | | result | string | Match outcome between buyer name and PSP-returned payer name. Values: `FULL_MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `EMAIL`. | | | buyer\_name | string | Name provided by the buyer at checkout. | | | payer\_name | string | Name returned by the PSP after payment. | | | checked\_at | string (ISO timestamp) | Timestamp when the risk check was performed. | | success\_url | | string | The URL to redirect the user to upon a successful transaction. | | transaction\_data | | array | Additional data related to the transaction. | | transaction\_description | | string | A description of the transaction. | | transaction\_documents | | array | List of transaction-related documents. | | webhook\_url | | string | The URL for webhook notifications related to this transaction. | | on\_behalf\_of | | string | ID of the entity on whose behalf the payin was created. Automatically inherited from the associated checkout session when applicable. Format: `ent_*` | # Payin Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/payin-webhook These are the events for which webhooks will be triggered When a payin is associated with a Checkout OBO session, all webhook payloads include the `on_behalf_of` field (the entity ID) in the `data` object. This field is omitted when OBO is not used. ## Payin Status specific events These are the events created and triggered when the status of the payin changes. | Event | Description | Default (on/off) | | :------------------------------ | :---------------------------------------------------- | :--------------- | | payin.requires\_payment\_method | Triggers when the status is requires\_payment\_method | On | | payin.requires\_action | Triggers when the status is requires\_action | On | | payin.processing | Triggers when the status is processing | On | | payin.succeeded | Triggers when the status is succeeded | On | | payin.cancelled | Triggers when the payin is cancelled | Off | ## payin.requires\_payment\_method ```json JSON expandable theme={null} { "type": "payin.requires_payment_method", "created_at": "2024-10-07T07:10:21.894488Z", "data": { "id": "pay_ahfafooi7fibakbfahoan", "object": "payin", "status": "requires_payment_method", "amount": 10000, "amount_paid": 0, "invoice_currency": "USD", "holding_currency": "USD", "confirm": false, "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": null, "latest_payment_attempt": "", "latest_payment_attempt_data": null, "payment_attempts": [], "reference_id": "order_12345", "transaction_description": "1 x Product", "transaction_documents": [], "transaction_data": [], "items": [], "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "statement_descriptor": "tzp*mystore", "status_description": "", "partially_paid": false, "paid_in_excess": false, "cancelled_at": null, "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2024-10-07T07:10:21.894488Z" }, "id": "evt_auigfiafaaaufaeoanfgohuehg", "object": "event" } ``` ## payin.requires\_action ```json JSON expandable theme={null} { "type": "payin.requires_action", "created_at": "2024-10-07T07:11:05.123456Z", "data": { "id": "pay_ahfafooi7fibakbfahoan", "object": "payin", "status": "requires_action", "amount": 10000, "amount_paid": 0, "invoice_currency": "USD", "holding_currency": "USD", "confirm": true, "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "issuing_country": "sg", "three_d_secure": { "result": "required" } } }, "latest_payment_attempt": "pat_bfiuafuiafianifnao", "latest_payment_attempt_data": { "id": "pat_bfiuafuiafianifnao", "object": "payment_attempt", "payin": "pay_ahfafooi7fibakbfahoan", "status": "requires_action", "amount": 10000, "charge_currency": "USD", "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "issuing_country": "sg", "three_d_secure": { "result": "required" } } }, "metadata": null, "created_at": "2024-10-07T07:11:05.123456Z" }, "payment_attempts": ["pat_bfiuafuiafianifnao"], "reference_id": "order_12345", "transaction_description": "1 x Product", "transaction_documents": [], "transaction_data": [], "items": [], "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "statement_descriptor": "tzp*mystore", "status_description": "", "partially_paid": false, "paid_in_excess": false, "cancelled_at": null, "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2024-10-07T07:10:21.894488Z" }, "id": "evt_auigfiafaaaufaeoanfgohuehg", "object": "event" } ``` ## payin.processing ```json JSON expandable theme={null} { "type": "payin.processing", "created_at": "2024-10-07T07:12:33.456789Z", "data": { "id": "pay_ahfafooi7fibakbfahoan", "object": "payin", "status": "processing", "amount": 10000, "amount_paid": 0, "invoice_currency": "USD", "holding_currency": "USD", "confirm": true, "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "issuing_country": "sg", "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "latest_payment_attempt": "pat_bfiuafuiafianifnao", "latest_payment_attempt_data": { "id": "pat_bfiuafuiafianifnao", "object": "payment_attempt", "payin": "pay_ahfafooi7fibakbfahoan", "status": "processing", "amount": 10000, "charge_currency": "USD", "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "issuing_country": "sg", "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "metadata": null, "created_at": "2024-10-07T07:11:05.123456Z" }, "payment_attempts": ["pat_bfiuafuiafianifnao"], "reference_id": "order_12345", "transaction_description": "1 x Product", "transaction_documents": [], "transaction_data": [], "items": [], "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "statement_descriptor": "tzp*mystore", "status_description": "", "partially_paid": false, "paid_in_excess": false, "cancelled_at": null, "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2024-10-07T07:10:21.894488Z" }, "id": "evt_auigfiafaaaufaeoanfgohuehg", "object": "event" } ``` ## payin.succeeded ```json JSON expandable theme={null} { "type": "payin.succeeded", "created_at": "2024-10-07T07:13:47.789012Z", "data": { "id": "pay_ahfafooi7fibakbfahoan", "object": "payin", "status": "succeeded", "amount": 10000, "amount_paid": 10000, "invoice_currency": "USD", "holding_currency": "USD", "confirm": true, "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=", "customer": "cus_crtqrhth90j0121gpt50", "on_behalf_of": "ent_d3inm6ami8u10oqfm", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "cardholder_name": "Andrea Lark", "issuing_country": "sg", "checks": { "cvc_check": "pass" }, "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "latest_payment_attempt": "pat_bfiuafuiafianifnao", "latest_payment_attempt_data": { "id": "pat_bfiuafuiafianifnao", "object": "payment_attempt", "payin": "pay_ahfafooi7fibakbfahoan", "status": "succeeded", "amount": 10000, "charge_currency": "USD", "balance_transaction": "btr_d679f6dqd9ne66lsngb0", "refunded": false, "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "cardholder_name": "Andrea Lark", "issuing_country": "sg", "checks": { "cvc_check": "pass" }, "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "fx_transaction": { "id": "fx_d209ek2fhufa9pkp5c4g", "object": "fx_transaction", "exchange_rate": 1.0, "initial": { "amount": 10000, "currency": "USD" }, "final": { "amount": 10000, "currency": "USD" } }, "reference_id": "TR000001385673188", "status_description": "", "metadata": null, "created_at": "2024-10-07T07:11:05.123456Z" }, "payment_attempts": ["pat_bfiuafuiafianifnao"], "reference_id": "order_12345", "transaction_description": "1 x Product", "transaction_documents": [], "transaction_data": [], "items": [], "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "statement_descriptor": "tzp*mystore", "status_description": "", "partially_paid": false, "paid_in_excess": false, "cancelled_at": null, "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2024-10-07T07:10:21.894488Z" }, "id": "evt_auigfiafaaaufaeoanfgohuehg", "object": "event" } ``` ## payin.cancelled ```json JSON expandable theme={null} { "type": "payin.cancelled", "created_at": "2024-10-07T07:15:00.000000Z", "data": { "id": "pay_ahfafooi7fibakbfahoan", "object": "payin", "status": "cancelled", "amount": 10000, "amount_paid": 0, "invoice_currency": "USD", "holding_currency": "USD", "confirm": false, "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": null, "latest_payment_attempt": "", "latest_payment_attempt_data": null, "payment_attempts": [], "reference_id": "order_12345", "transaction_description": "1 x Product", "transaction_documents": [], "transaction_data": [], "items": [], "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "statement_descriptor": "tzp*mystore", "status_description": "", "partially_paid": false, "paid_in_excess": false, "cancelled_at": "2024-10-07T07:15:00.000000Z", "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2024-10-07T07:10:21.894488Z" }, "id": "evt_auigfiafaaaufaeoanfgohuehg", "object": "event" } ``` ## Payment\_Attempt Specific Events: These events are created and triggered when something of interest happens for a payment attempt. | Event | Description | Default (on/off) | | :------------------------- | :---------------------------------- | :--------------- | | payment\_attempt.failed | When a payment\_attempt fails | On | | payment\_attempt.succeeded | When the payment\_attempt succeeds | Off | | payment\_attempt.reversed | When a payment\_attempt is reversed | On | ### payment\_attempt.failed ```json JSON expandable theme={null} { "type": "payment_attempt.failed", "created_at": "2024-10-07T07:12:00.000000Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "failed", "amount": 10000, "charge_currency": "USD", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": { "type": "card", "card": { "last4": "0002", "scheme": "visa", "funding": "credit", "cardholder_name": "Andrea Lark", "issuing_country": "sg", "checks": { "cvc_check": "fail" }, "three_d_secure": { "eci": "07", "result": "failed", "version": "2.2.0" } } }, "fx_transaction": null, "balance_transaction": null, "refunded": false, "reference_id": "TR000001385673188", "status_description": "Card declined", "metadata": null, "created_at": "2024-10-07T07:11:55.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### payment\_attempt.succeeded ```json JSON expandable theme={null} { "type": "payment_attempt.succeeded", "created_at": "2024-10-07T07:13:47.789012Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "succeeded", "amount": 10000, "charge_currency": "USD", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "cardholder_name": "Andrea Lark", "issuing_country": "sg", "checks": { "cvc_check": "pass" }, "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "fx_transaction": { "id": "fx_d209ek2fhufa9pkp5c4g", "object": "fx_transaction", "exchange_rate": 1.0, "initial": { "amount": 10000, "currency": "USD" }, "final": { "amount": 10000, "currency": "USD" } }, "balance_transaction": "btr_d679f6dqd9ne66lsngb0", "refunded": false, "reference_id": "TR000001385673188", "status_description": "", "metadata": null, "created_at": "2024-10-07T07:11:05.123456Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### payment\_attempt.reversed ```json JSON expandable theme={null} { "type": "payment_attempt.reversed", "created_at": "2024-10-07T07:14:30.000000Z", "data": { "id": "pat_ahfafooi7ibakbfahoan", "object": "payment_attempt", "payin": "pay_bfiuafuiafianifnao", "status": "reversed", "amount": 10000, "charge_currency": "USD", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": { "type": "card", "card": { "last4": "4242", "scheme": "visa", "funding": "credit", "cardholder_name": "Andrea Lark", "issuing_country": "sg", "checks": { "cvc_check": "pass" }, "three_d_secure": { "eci": "05", "result": "authenticated", "version": "2.2.0" } } }, "fx_transaction": { "id": "fx_d209ek2fhufa9pkp5c4g", "object": "fx_transaction", "exchange_rate": 1.0, "initial": { "amount": 10000, "currency": "USD" }, "final": { "amount": 10000, "currency": "USD" } }, "balance_transaction": "btr_d679f6dqd9ne66lsngb0", "refunded": false, "reference_id": "TR000001385673188", "status_description": "", "metadata": null, "created_at": "2024-10-07T07:11:05.123456Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ## Other Events: | Event | Description | Default (on/off) | | :------------ | :----------------- | :--------------- | | payin.created | A payin is created | Off | ### payin.created ```json JSON expandable theme={null} { "type": "payin.created", "created_at": "2024-10-07T07:10:21.894488Z", "data": { "id": "pay_ahfafooi7fibakbfahoan", "object": "payin", "status": "requires_payment_method", "amount": 10000, "amount_paid": 0, "invoice_currency": "USD", "holding_currency": "USD", "confirm": false, "client_token": "JsU19R_Li9cwVksJGUfAajZ3r2A9ArU7Qk3j5r0cpVg=", "customer": "cus_crtqrhth90j0121gpt50", "customer_details": { "country": "SG", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "billing_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "shipping_details": { "address": { "city": "Singapore", "country": "SG", "line1": "1st Street", "line2": "2nd Avenue", "postal_code": "43004", "state": "Singapore" }, "label": "Home", "name": "Andrea Lark", "phone": { "calling_code": "65", "number": "87654321" } }, "payment_method_details": null, "latest_payment_attempt": "", "latest_payment_attempt_data": null, "payment_attempts": [], "reference_id": "order_12345", "transaction_description": "1 x Product", "transaction_documents": [], "transaction_data": [], "items": [], "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "statement_descriptor": "tzp*mystore", "status_description": "", "partially_paid": false, "paid_in_excess": false, "cancelled_at": null, "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2024-10-07T07:10:21.894488Z" }, "id": "evt_auigfiafaaaufaeoanfgohuehg", "object": "event" } ``` # Payment Attempts Source: https://developer.tazapay.com/api-reference/tazapay-api/payment-attempts-1 A Tazapay Payment Attempt refers to an instance where a transaction is attempted through the Tazapay platform, either as part of a checkout process or other payment-related workflows. Each payment attempt captures essential details of the transaction, including the amount, currency, payment method, status, and any relevant metadata. ## Object Structure ```json JSON expandable theme={null} { "status": "success", "message": "", "data": { "amount": 9899, "balance_transaction": "btr_d679f6dqd9ne66lsngb0", "charge_currency": "PLN", "created_at": "2023-07-23T08:03:29.718275Z", "customer": "cus_d209e84kspu2df5phfm0", "customer_details": { "country": "PL", "email": "sowajan1010@gmail.com", "name": "Jan", "phone": { "calling_code": "48", "number": "1234369" } }, "fx_transaction": { "exchange_rate": 0.219768, "final": { "amount": 2173, "currency": "EUR" }, "id": "fx_d209ek2fhufa9pkp5c4g", "initial": { "amount": 9888, "currency": "PLN" }, "object": "fx_transaction" }, "id": "pat_d209ek5qd9ne66lsn6gg", "metadata": null, "object": "payment_attempt", "payin": "chk_d209e85qd65u66lsn1g0", "payment_method_details": { "card": { "cardholder_name": "jan cebella", "checks": { "cvc_check": "pass" }, "expiry": { "month": 7, "year": 2031 }, "first6": "428771", "funding": "debit", "issuer": "ing bank slaski sa", "issuing_country": "pl", "last4": "6095", "scheme": "visa", "three_d_secure": { "eci": "05", "result": "attempt_acknowledged", "version": "2.2.0" } }, "type": "card" }, "reference_id": "TR000001385673188", "refunded": "true", "status": "succeeded", "status_description": "" } ``` ## Parameters ### Payment Attempt | Parameter | Type | Description | | :----------------------- | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | | id | string | The Tazapay ID of the payment attempt. | | object | string | The object type, which is "payment\_attempt". | | created\_at | string (ISO Date) | The date and time when the payment attempt was created. | | amount | number | The amount attempted to be paid in the charge currency. | | balance\_transaction | string | The balance transaction id associated with the payment attempt. | | customer | string | The unique Tazapay customer id. | | customer\_details | object | Customer Details. | | reference\_id | string | Reference id attached to the payment attempt. | | charge\_currency | string | The currency in which the payment was attempted (e.g., SGD). | | payin | string | The reference to the payin object related to the checkout transaction. | | payment\_method\_details | string | The payment method details used in this attempt | | refunded | boolean | Indicates whether the payment attempt has been refunded. | | status | string | The status of the payment attempt (e.g., succeeded, failed). | | status\_description | string | A description providing more information about the payment attempt status | | final\_currency | string | The final currency after the payment is converted, if applicable (e.g., USD). | | fx\_transaction | object | Details about the foreign exchange transaction, if any. Check [FX transaction](/api-reference/tazapay-api/fx-transaction-object) object | | metadata | json | Additional key value pairs related to the payment attempt (optional). | # Payout Source: https://developer.tazapay.com/api-reference/tazapay-api/payout Payout allows businesses to disburse payments to individuals or other businesses globally. It facilitates cross-border payouts by enabling transfers to local bank accounts, ensuring compliance with international regulations, and offering multiple payout options such as bank transfers, digital wallets, or local payment methods ## Object Structure ```json Swift Bank Payout expandable theme={null} { "amount": 100000, "balance_transaction": "btr_d35pv4qcl8imrv60", "beneficiary": "bnf_d3inm6ami8u10oqfg", "beneficiary_details": { "address": { "city": "Shanghai", "country": "CN", "line1": "Room 1208, No. 88 Century Avenue", "postal_code": "200120", "state": "Shanghai" }, "date_of_birth": "2003-04-04", "nationality": "CN", "destination": "bnk_crv7k337eoqgk10pqp40", "destination_details": { "bank": { "account_number": "33050167624000001030", "account_type": "savings", "bank_codes": { "swift_code": "PCBCCNBJZJX" }, "bank_name": "CHINA CONSTRUCTION BANK, ZHEJIANG BRANCH", "branch_name": "Century Avenue", "country": "CN", "currency": "USD", "firc_required": false, "purpose_code": "", "transfer_type": "swift" }, "type": "bank" }, "documents": [{ "type": "identity_proof", "url": "https://drive.google.com/file/d/1q5kk5YKcCojdTYir-rONXjN7szuXE16m/view?usp=sharing" }], "email": "importandexport@gmail.com", "name": "IMPORT AND EXPORT CO., LTD", "name_local": "进出口有限公司", "national_identification_number": "", "party_classification": "", "phone": { "calling_code": "86" "number": "9231231231" }, "registration_number": "648302704", "tax_id": "", "type": "business" }, "charge_type": "ours", "confirmation_documents": [ { "key": "mt103", "type": "string", "value": "{1:FHFLEND0XXX0000000000}{2:I103SCBLUS33XXXXN}{3:{108:ST10302510092922}{111:001}{121:372ff3b1-\nd12d-431c-8c9f-f19eb2507285}}{4:\n:20:ST1050254092922\n:23B:CRED\n:32A:251009USD4863,52\n:33B:USD4863,52\n:50K:/10096543269\nTrade Pe Tech Private Limited\nBarrister Rajni Patel Marg, Nariman\nPoint 61, Mittal Chambers 400021 Mu\nmbai Maharashtra/INDIA\n:52D:/0105552976\nTAZAPAY PTE. LTD.\n8 VEDAEK BOULEVARD,15-02, SUFEC T\nOWYT THREE,SINGAPORE,ZIP 038988\n/SINGAPORE\n:57A:ICICINBBCTS\n:59:/119405003646\nTRADE PE TECH PVT LTD-OPGSP MRROR N\nOSTRO A/C\nIN\n/INDIA\n:70:Nostro Payout for settlement\n:71A:OUR\n:72:/ACC/INCKIEBCTS/CITI BANK N.A./\n-}" } ], "created_at": "2025-09-18T10:07:35.101708Z", "currency": "USD", "documents": [{ "type": "invoice", "url": "https://drive.google.com/file/d/1q5kk5YKcCojdTYir-rONXjN7szuXE16m/view?usp=sharing" }], "holding_currency": "USD", "holding_fx_quote": "fx_d35tjpnfigp2dt2hgg", "holding_fx_transaction": { "exchange_rate": 1, "final": { "amount": 10000000, "currency": "USD" }, "id": "fx_d35tjpnfigp2dt2hgg", "initial": { "amount": 10000000, "currency": "USD" }, "object": "fx_transaction" }, "id": "pot_d35tjpn4qcl8iv30", "logistics_tracking_details": [ { "tracking_number":"5436789", "logistics_provider":{"name":"DHL Express","code":"UH783"} } ], "metadata": null, "mt103": "{1:FHFLEND0XXX0000000000}{2:I103SCBLUS33XXXXN}{3:{108:ST10302510092922}{111:001}{121:372ff3b1-\nd12d-431c-8c9f-f19eb2507285}}{4:\n:20:ST1050254092922\n:23B:CRED\n:32A:251009USD4863,52\n:33B:USD4863,52\n:50K:/10096543269\nTrade Pe Tech Private Limited\nBarrister Rajni Patel Marg, Nariman\nPoint 61, Mittal Chambers 400021 Mu\nmbai Maharashtra/INDIA\n:52D:/0105552976\nTAZAPAY PTE. LTD.\n8 VEDAEK BOULEVARD,15-02, SUFEC T\nOWYT THREE,SINGAPORE,ZIP 038988\n/SINGAPORE\n:57A:ICICINBBCTS\n:59:/119405003646\nTRADE PE TECH PVT LTD-OPGSP MRROR N\nOSTRO A/C\nIN\n/INDIA\n:70:Nostro Payout for settlement\n:71A:OUR\n:72:/ACC/INCKIEBCTS/CITI BANK N.A./\n-}", "object": "payout", "on_behalf_of": "ent_d68uqetjd0fmussfd1q0", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 10000000, "currency": "USD" }, "id": "fx_d35tfigo4p2dt2hh0", "initial": { "amount": 10000000, "currency": "USD" }, "object": "fx_transaction" }, "purpose": "PYR003", "quote": "poq_d3inm6ami8u10oqfh", "reference_id": "INV-2024-CN-8923", "statement_descriptor": "Import Payment", "status": "succeeded", "status_description": "", "tracking_details": { "tracking_number": "7833d-34b4-478-aac8-1184beae", "tracking_type": "uetr" }, "transaction_description": "Payment for goods acc 125", "type": "swift" } ``` ```json Local Bank Payout expandable theme={null} { "status": "success", "message": "", "data": { "amount": 3000000, "balance_transaction": "btr_dhuvflvi5frlneafr0", "beneficiary": "bnf_d0dla9u8dpp4edio0", "beneficiary_details": { "address": null, "date_of_birth": "", "nationality": "DE", "destination": "", "destination_details": { "bank": { "account_type": "", "bank_codes": { "swift_code": "FBDEFF" }, "bank_name": "ER VOLKSBANK EG", "branch_name": "", "country": "DE", "currency": "EUR", "firc_required": false, "iban": "DE535019045650474185", "purpose_code": "", "transfer_type": "any" }, "type": "bank" }, "documents": [], "email": "", "name": "GMBH", "name_local": "", "national_identification_number": "", "party_classification": "", "phone": { "calling_code": "49" }, "registration_number": "", "tax_id": "", "type": "business" }, "charge_type": "", "confirmation_documents": [], "created_at": "2025-09-16T08:27:41.832790Z", "currency": "EUR", "documents": [], "holding_currency": "USD", "holding_fx_quote": "fx_d34hc7loipp34fmg", "holding_fx_transaction": { "exchange_rate": 0.846438, "final": { "amount": 3000000, "currency": "EUR" }, "id": "fx_d34flc7loipp34fmg", "initial": { "amount": 3544266, "currency": "USD" }, "object": "fx_transaction" }, "id": "pot_d34hlvi5frlneafo0", "local": { "fund_transfer_network": "sepa" }, "logistics_tracking_details": [ { "tracking_number":"5436789", "logistics_provider":{"name":"DHL Express","code":"UH783"} } ], "metadata": null, "mt103": "", "object": "payout", "on_behalf_of": "ent_d68uq89jd0fvsnsfd1q0", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 3000000, "currency": "EUR" }, "id": "fx_d34huvflc7pp34fm0", "initial": { "amount": 3000000, "currency": "EUR" }, "object": "fx_transaction" }, "purpose": "PYR001", "quote": "poq_d3inm6ami8u10oqfk", "reference_id": "DE-LOG-2024-0909", "statement_descriptor": "Logistics Payment", "status": "succeeded", "status_description": "", "tracking_details": { "tracking_number": "098771252590P9A", "tracking_type": "UTR" }, "transaction_description": "Payment for logistic services 9-09", "type": "local" } } ``` ```json Local Payment Network Payout expandable theme={null} { "status": "success", "message": "", "data": { "amount": 144, "balance_transaction": "btr_d35v6ddendp1ul1p0", "beneficiary": "bnf_d2pkuchg06m8tvjg", "beneficiary_details": { "address": null, "date_of_birth": "", "nationality": "BR", "destination": "", "destination_details": { "local_payment_network": { "currency": "BRL", "deposit_key": "fep@gmail.com", "type": "pix_brl" }, "type": "local_payment_network" }, "documents": [], "email": "fep@gmail.com", "name": "Feete Pereira", "name_local": "", "national_identification_number": "", "party_classification": "", "phone": null, "registration_number": "", "tax_id": "3879876743", "type": "individual" }, "charge_type": "", "confirmation_documents": [], "created_at": "2025-09-18T11:56:35.627500Z", "currency": "BRL", "documents": [], "holding_currency": "USD", "holding_fx_quote": "fx_d35vfigo4p2dt8ecg", "holding_fx_transaction": { "exchange_rate": 5.158393, "final": { "amount": 144, "currency": "BRL" }, "id": "fx_d35vfigo4p2dt8ecg", "initial": { "amount": 28, "currency": "USD" }, "object": "fx_transaction" }, "id": "pot_d35v6sp8dp1ul1m0", "local": { "fund_transfer_network": "sepa" }, "logistics_tracking_details": [], "metadata": null, "mt103": "", "object": "payout", "on_behalf_of": "", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 144, "currency": "BRL" }, "id": "fx_d35v6go4p2dt8ec0", "initial": { "amount": 144, "currency": "BRL" }, "object": "fx_transaction" }, "payout_quote": "", "purpose": "PYR001", "quote": "poq_d3inm6ami8u10oqfl", "reference_id": "BR-PIX-2024-3879", "statement_descriptor": "Freelancer Payment", "status": "succeeded", "status_description": "", "tracking_details": { "tracking_number": "E1234567820240918115635627", "tracking_type": "pix_id" }, "transaction_description": "Freelance design services payment", "type": "local_payment_network" } } ``` ```json Transfer Within Tazapay expandable theme={null} { "status": "success", "message": "", "data": { "amount": 44000, "balance_transaction": "btr_d35sqe74qcl8im850", "beneficiary": "bnf_d35spsnl8imrh3gv0", "beneficiary_details": { "address": {}, "date_of_birth": "", "nationality": "SG", "destination": "", "destination_details": { "tazapay_account": { "deposit_address": "ce4f51ue@tzp" }, "type": "tazapay_account" }, "documents": [], "email": "info@trading.com", "name": "T Co., Limited", "name_local": "", "national_identification_number": "", "party_classification": "", "phone": {}, "registration_number": "", "tax_id": "", "type": "business" }, "charge_type": "", "confirmation_documents": [], "created_at": "2025-09-18T09:13:28.633167Z", "currency": "USD", "documents": [], "holding_currency": "USD", "holding_fx_quote": "fx_d35sfigo4p2dsvsvg", "holding_fx_transaction": { "exchange_rate": 1, "final": { "amount": 44000, "currency": "USD" }, "id": "fx_d35sqe7figo4p2dsvsvg", "initial": { "amount": 44000, "currency": "USD" }, "object": "fx_transaction" }, "id": "pot_d5sqe7cl8imrh4810", "local": { "fund_transfer_network": "sepa" }, "logistics_tracking_details": [], "metadata": null, "mt103": "", "object": "payout", "on_behalf_of": "", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 44000, "currency": "" }, "id": "fx_d35sqe7figo4psvt00", "initial": { "amount": 44000, "currency": "USD" }, "object": "fx_transaction" }, "payout_quote": "", "purpose": "PYR003", "quote": "poq_d3inm6ami8u10oqfm", "reference_id": "TZP-ACC-2024-1892", "statement_descriptor": "Trading Payment", "status": "succeeded", "status_description": "", "tracking_details": { "tracking_number": "TZP-001-2024-9876", "tracking_type": "internal" }, "transaction_description": "Payment for goods acc 001", "type": "tazapay_account" } } ``` ```json Crypto Payout expandable theme={null} { "status": "success", "message": "", "data": { "amount": 122225, "balance_transaction": "btr_dag4eup1ekl94qrlg", "beneficiary": "bnf_d35eag4eupl94qrig", "beneficiary_details": { "address": { "city": "Vrtmore", "country": "JM", "line1": "it12 3cwth", "postal_code": "00000", "state": "Vortmore" }, "date_of_birth": "2003-04-04", "nationality": "JM", "destination": "", "destination_details": { "type": "wallet", "wallet": { "currency": "USDC", "deposit_address": "09e53bcac0f2edxnjsui87f8bb7a9faf64789ed8", "type": "ethereum" } }, "documents": [], "email": "", "name": "Scott", "name_local": "", "national_identification_number": "", "party_classification": "third_party", "phone": {}, "registration_number": "", "tax_id": "", "type": "individual" }, "charge_type": "", "confirmation_documents": [], "created_at": "2025-09-17T16:43:44.378053Z", "currency": "USD", "documents": [], "holding_currency": "USD", "holding_fx_quote": "fx_d35eag74p2drbeug", "holding_fx_transaction": { "exchange_rate": 1, "final": { "amount": 122225, "currency": "USD" }, "id": "fx_d35eag74p2drbeug", "initial": { "amount": 122225, "currency": "USD" }, "object": "fx_transaction" }, "id": "pot_d35eag4ekl94qri0", "local": { "fund_transfer_network": "sepa" }, "logistics_tracking_details": [], "metadata": null, "mt103": "", "object": "payout", "on_behalf_of": "", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 122225, "currency": "USDC" }, "id": "fx_d35igo4p2drbeu0", "initial": { "amount": 122225, "currency": "USD" }, "object": "fx_transaction" }, "payout_quote": "", "purpose": "PYR030", "quote": "poq_d3inm6ami8u10oqfn", "reference_id": "CRYPTO-COM-2024-9817", "statement_descriptor": "Commission Payment", "status": "succeeded", "status_description": "", "tracking_details": { "tracking_number": "0xadef30173d3dd42333779a683c1404e50567e03fb4daef4f850f415789f559f", "tracking_type": "transaction_hash" }, "transaction_description": "Commission payment for Q3 2024", "type": "wallet" } } ``` ```json Reversed Payout expandable theme={null} { "status": "success", "message": "", "data": { "amount": 9400, "balance_transaction": "btr_d66p4jdv8bk93hfrpqvg", "beneficiary": "bnf_d66p36tv8bk93hfrpq40", "beneficiary_details": { "address": { "city": "chennai", "country": "SG", "line1": "line1", "line2": "test", "postal_code": "34567", "state": "test" }, "date_of_birth": "", "destination": "", "destination_details": { "bank": { "account_number": "123456789012", "account_type": "", "bank_codes": { "swift_code": "DBSSSGSGXXX" }, "bank_name": "Example Bank Ltd", "branch_name": "", "country": "SG", "currency": "SGD", "firc_required": false, "purpose_code": "", "transfer_type": "any" }, "type": "bank" }, "documents": [], "email": "", "is_doc_verification_required": false, "name": "SGD", "name_local": "", "national_identification_number": "", "nationality": "", "party_classification": "", "phone": null, "registration_number": "", "status": "active", "tax_id": "", "type": "business", "verification_status": "succeeded" }, "charge_type": "", "confirmation_documents": [], "created_at": "2026-02-12T08:41:49.433474Z", "currency": "SGD", "destination_fx_quote": "fx_d66p4jc2rt3in2223tog", "documents": [], "holding_currency": "SGD", "holding_fx_quote": "fx_d66p4jc2rt3in2223to0", "holding_fx_transaction": { "exchange_rate": 1, "final": { "amount": 9400, "currency": "SGD" }, "id": "fx_d66p4jc2rt3in2223to0", "initial": { "amount": 9400, "currency": "SGD" }, "object": "fx_transaction" }, "id": "pot_d66p4jdv8bk93hfrpqs0", "local": { "fund_transfer_network": "fast" }, "logistics_tracking_details": [], "metadata": null, "mt103": "", "object": "payout", "on_behalf_of": "", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 9400, "currency": "SGD" }, "id": "fx_d66p4jc2rt3in2223tog", "initial": { "amount": 9400, "currency": "SGD" }, "object": "fx_transaction" }, "purpose": "PYR001", "quote": "", "reference_id": "", "reversal_balance_transaction": "btr_d66qoo5v8bk93hfrqr40", "reversal_holding_fx_transaction": { "exchange_rate": 1, "final": { "amount": 9400, "currency": "SGD" }, "id": "fx_d66qoo42rt3in2223vng", "initial": { "amount": 9400, "currency": "SGD" }, "object": "fx_transaction" }, "reversal_payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 9400, "currency": "SGD" }, "id": "fx_d66qoo42rt3in2223vn0", "initial": { "amount": 9400, "currency": "SGD" }, "object": "fx_transaction" }, "statement_descriptor": "", "status": "reversed", "status_description": "PR1001", "tracking_details": { "tracking_number": "", "tracking_type": "" }, "transaction_description": "100.35 SGD will be deducted from your balance", "type": "local" } } ``` ## Object Parameters ### Payout | Field | Type | Description | | :-------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount | number | The total amount for the payout transaction. | | available\_balance | integer | Available balance in the holding currency account after this payout is processed. | | balance\_transaction | string | The Tazapay ID of the balance transaction associated with the payout. | | beneficiary | string | The Tazapay ID of the beneficiary receiving the payout. | | beneficiary\_details | object | The details of the beneficiary. [**Beneficiary Details Object**](/api-reference/tazapay-api/beneficiary) | | charge\_type | enum | The charge type for the payout. \[Values: `ours`, `shared`] | | confirmation\_documents | array | Array of confirmation documents (MT103, MT199, FIRC, etc.). Each contains `key` (document type), `type` (MIME type), `value` (content/URL). | | created\_at | string | The timestamp when the payout was created (ISO 8601). | | currency | string | The currency of the payout amount. | | documents | array | The list of documents related to the payout. | | holding\_currency | string | The currency used for holding funds before payout. | | holding\_fx\_quote | string | The FX quote ID used for holding currency. | | holding\_fx\_transaction | object | The FX transaction details for the holding currency. [**FX Transaction Object**](/api-reference/tazapay-api/fx-transaction-object) | | id | string | The unique Tazapay identifier for the payout. | | is\_balance\_sufficient | boolean | Indicates whether the account has sufficient balance to process this payout. | | local | object | Local payout configuration object containing `fund_transfer_network` (e.g., "chats", "fps", "sepa"). | | logistics\_tracking\_details | array | Array of logistics tracking information. Each contains `tracking_number`, `logistics_provider`, and `description`. | | metadata | object | Key-value metadata attached to the payout. | | mt103 | string | The MT103 SWIFT message reference for the payout (if applicable). | | object | string | The type of object, always `"payout"`. | | on\_behalf\_of | string | The account ID if the payout was made on behalf of another entity. | | payout\_fx\_transaction | object | The FX transaction details for payout currency. ([**FX Transaction Object**](/api-reference/tazapay-api/fx-transaction-object)) | | payout\_quote | string | The payout quote reference (if applicable). | | purpose | enum | The purpose code for the payout. \[Values: PYR001–PYR030]. Click here for the detailed list. | | quote | string | ID of the payout quote used to lock exchange rates for this payout. Begins with 'poq\_'. | | reference\_id | string | The merchant's reference ID for the payout. | | reversal\_balance\_transaction | string | Id of the reverse balance transaction object linked to this payout. Only present when status is `reversed`. | | reversal\_payout\_fx\_transaction | object | Reversal FX transaction details for payout currency. ([**FX Transaction Object**](/api-reference/tazapay-api/fx-transaction-object)) | | statement\_descriptor | string | The statement descriptor that appears on the beneficiary's bank statement. | | status | enum | The current status of the payout. \[Values: `Processing`, `Requires Approval`, `Requires Action`, `Succeeded`, `Failed`, `Cancelled`, `Reversed`, `Initiator Bank Hold`] | | status\_description | string | A description of the current payout status. | | tracking\_details | object | Tracking details of the payout. ([**Tracking Details Object**](/api-reference/tazapay-api/payout#tracking-details)) | | transaction\_description | string | A description of the payout transaction provided by the merchant. | | type | enum | The type of payout. \[Values: `swift`, `local`, `wallet`, `local_payment_network`, `tazapay_account`] | ### Tracking Details | Field | Type | Description | | :--------------- | :----- | :-------------------------------------------------------------- | | tracking\_number | string | The tracking number (UETR, UTR, transaction hash, etc.). | | tracking\_type | enum | The tracking type. \[Values: `uetr`, `utr`, `transaction_hash`] | ### Local | Field | Type | Description | | :---------------------- | :----- | :--------------------------------------------------------------------------------------------------- | | fund\_transfer\_network | string | The local fund transfer network used for local payouts (e.g., "chats", "fps", "sepa", "rtgs", "ach") | # Payout Bank Source: https://developer.tazapay.com/api-reference/tazapay-api/payout-bank get /v3/metadata/payout/bank This allows you to check the requirements with respect to bank fields for a given beneficiary country. These requirements will be made live on 30th April 2025, merchants must adhere to these requirements and update the integration on or before the deadline. # Payout Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/payout-webhooks ## Payout status specific events | Event | Description | Default | | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `payout.requires_approval` | Triggered when the status is requires\_approval | Off | | `payout.requires_action` | Triggered when the status is requires\_action | Off | | `payout.requires_funding` | Triggered when the status is requires\_funding | On | | `payout.processing` | Triggered when the status is processing | On | | `payout.succeeded` | Triggered when the status is succeeded | On | | `payout.failed` | Triggered when the status is failed | On | | `payout.cancelled` | Triggered when the payout is cancelled | On | | `payout.reversed` | Triggered when the payout is reversed | On | | `payout.proof_of_payment_generated` | Triggered when the proof of payment is updated | On | | `payout.initiator_bank_hold` | Triggered when the payout is placed on hold by the initiating bank for review and will be released once the transaction is cleared by the bank. | On | ## Other Events | Event | Description | Default (On / Off) | | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------- | | `payout.created` | Triggered when a payout is created | Off | | `payout.mt103_generated` | Triggered when MT103 is added to a payout | Off | | `payout.mt199_generated` | Triggered when MT199 is added to a payout | Off | | `payout.firc_generated` | Triggered when FIRC is added to a payout | Off | | `payout.other_document_generated` | Triggered when any other document type is added | Off | | `payout.gpi_tracking` | Triggered on every new SWIFT GPI hop (UETR-based tracking). Additive — does not change `payout.status`. See [SWIFT GPI Tracking](/api-reference/tazapay-api/swift-gpi-tracking). | On | ## Sample Events ### payout.created ```json expandable theme={null} { "type": "payout.created", "id": "evt_ctbvv9o1l435sdu911tg", "object": "event", "created_at": "2024-12-10T08:45:27.349281559Z", "data": { "local": {}, "created_at": "2024-12-10T08:45:25.12005Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "bank_code": "INGBAU2SXXX", "branch_code": "INGBAU2SXXX" }, "account_number":"78393933", "bank_name": "Central Bank", "country": "BR", "currency": "BRL", "account_type": "savings" }, "type": "bank" }, "phone": { "calling_code": "55" }, "name": "Roman", "email": "akash@example.com", "type": "individual", "tax_id": "123.456.789-87" }, "payout_fx_transaction": { "initial": { "currency": "BRL", "amount": 10000 }, "final": { "currency": "BRL", "amount": 10000 }, "id": "fx_ctbvv905ha8onnfg24s0", "object": "fx_transaction", "exchange_rate": 1 }, "type": "local", "status": "processing", "purpose": "PYR001", "id": "pot_ctbvv96hi567m07e7q40", "holding_currency": "INR", "currency": "BRL", "beneficiary": "bnf_cs8bf4m6rf9979b4isq0", "object": "payout", "balance_transaction": "btr_ctbvv9ehi567m07e7q80", "amount": 10000, "local": { "fund_transfer_network": "pix" }, "logistics_tracking_details": [{ "tracking_number":"5436789", "logistics_provider":{"name":"DHL Express","code":"UH783"} }], "confirmation_documents": [{ "key": "mt103", "type": "string", "value": "{1:FHFLEND0XXX0000000000}{2:I103SCBLUS33XXXXN}{3:{108:ST10302510092922}{111:001}{121:372ff3b1-\nd12d-431c-8c9f-f19eb2507285}}{4:\n:20:ST1050254092922\n:23B:CRED\n:32A:251009USD4863,52\n:33B:USD4863,52\n:50K:/10096543269\nTrade Pe Tech Private Limited\nBarrister Rajni Patel Marg, Nariman\nPoint 61, Mittal Chambers 400021 Mu\nmbai Maharashtra/INDIA\n:52D:/0105552976\nTAZAPAY PTE. LTD.\n8 VEDAEK BOULEVARD,15-02, SUFEC T\nOWYT THREE,SINGAPORE,ZIP 038988\n/SINGAPORE\n:57A:ICICINBBCTS\n:59:/119405003646\nTRADE PE TECH PVT LTD-OPGSP MRROR N\nOSTRO A/C\nIN\n/INDIA\n:70:Nostro Payout for settlement\n:71A:OUR\n:72:/ACC/INCKIEBCTS/CITI BANK N.A./\n-}" }], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 10000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctbvv96hi567m07e7q3y" } } ``` ### payout.processing ```json expandable theme={null} { "type": "payout.processing", "id": "evt_ctbvv9o1l435sdu911t0", "object": "event", "created_at": "2024-12-10T08:45:27.305264108Z", "data": { "created_at": "2024-12-10T08:45:25.12005Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "bank_code": "INGBAU2SXXX", "branch_code": "INGBAU2SXXX" }, "bank_name": "Central Bank", "country": "BR", "currency": "BRL", "account_type": "savings" }, "type": "bank" }, "phone": { "calling_code": "55" }, "name": "Test1", "email": "musk@gmail.com", "type": "individual", "tax_id": "123" }, "payout_fx_transaction": { "initial": { "currency": "BRL", "amount": 10000 }, "final": { "currency": "BRL", "amount": 10000 }, "id": "fx_ctbvv905ha8onnfg24s0", "object": "fx_transaction", "exchange_rate": 1 }, "type": "local", "status": "processing", "purpose": "PYR001", "id": "pot_ctbvv96hi567m07e7q40", "holding_currency": "INR", "currency": "BRL", "beneficiary": "bnf_cs8bf4m6rf9979b4isq0", "object": "payout", "balance_transaction": "btr_ctbvv9ehi567m07e7q80", "amount": 10000, "local": { "fund_transfer_network": "pix" }, "logistics_tracking_details": [{ "tracking_number":"5436789", "logistics_provider":{"name":"DHL Express","code":"UH783"} }], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 10000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctbvv96hi567m07e7q3x" } } ``` ### payout.succeeded ```json expandable theme={null} { "type": "payout.succeeded", "id": "evt_ctc007o1l435sdu91250", "object": "event", "created_at": "2024-12-10T08:47:27.446050128Z", "data": { "tracking_details": { "tracking_number": "UETR20240311001", "tracking_type": "uetr" }, "created_at": "2024-12-10T08:45:25.12005Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "bank_code": "INGBAU2SXXX", "branch_code": "INGBAU2SXXX" }, "bank_name": "Central Bank", "country": "BR", "currency": "BRL", "account_type": "savings" }, "type": "bank" }, "phone": { "calling_code": "55" }, "name": "Test1", "email": "musk@gmail.com", "type": "individual", "tax_id": "123" }, "payout_fx_transaction": { "initial": { "currency": "BRL", "amount": 10000 }, "final": { "currency": "BRL", "amount": 10000 }, "id": "fx_ctbvv905ha8onnfg24s0", "object": "fx_transaction", "exchange_rate": 1 }, "type": "local", "status": "succeeded", "purpose": "PYR001", "id": "pot_ctbvv96hi567m07e7q40", "holding_currency": "INR", "currency": "BRL", "beneficiary": "bnf_cs8bf4m6rf9979b4isq0", "object": "payout", "balance_transaction": "btr_ctbvv9ehi567m07e7q80", "amount": 10000, "local": { "fund_transfer_network": "sepa" }, "logistics_tracking_details": [], "confirmation_documents": [ { "key": "mt103", "type": "application/pdf", "value": "/confirmations/pot_ctbvv96hi567m07e7q40_mt103.pdf" } ], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 10000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctbvv96hi567m07e7q3z" } } ``` ### payout.requires\_funding ```json expandable theme={null} { "type": "payout.requires_funding", "id": "evt_ctc02681l435sdu912pg", "object": "event", "created_at": "2024-12-10T08:51:37.346373409Z", "data": { "created_at": "2024-12-10T08:51:34.128328Z", "beneficiary_details": { "address": { "line1": "MG Road", "line2": "Adj ST Mary School", "postal_code": "10038", "city": "Delhi", "state": "Delhi", "country": "IN" }, "destination_details": { "bank": { "bank_codes": { "ifsc_code": "HDFR8897CA", "swift_code": "INGBAU2SXXX" }, "account_number": "1276472008763", "bank_name": "hdfc", "country": "IN", "currency": "INR", "purpose_code": "Test", "firc_required": true }, "type": "bank" }, "phone": { "calling_code": "91" }, "name": "test", "email": "test@example.com", "type": "individual" }, "payout_fx_transaction": { "initial": { "currency": "INR", "amount": 1000000000 }, "final": { "currency": "INR", "amount": 1000000000 }, "id": "fx_ctc025g5ha8onnfg2510", "object": "fx_transaction", "exchange_rate": 1 }, "type": "local", "status": "requires_funding", "purpose": "PYR001", "id": "pot_ctc025mhi567m07e7r50", "holding_currency": "GBP", "currency": "INR", "beneficiary": "bnf_crv7k31h1l071n2fkbjg", "object": "payout", "amount": 1000000000, "available_balance": 50000000, "is_balance_sufficient": false, "local": { "fund_transfer_network": "rtgs" }, "logistics_tracking_details": [], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 1000000000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctc025mhi567m07e7r4z" } } ``` ### payout.requires\_approval ```json expandable theme={null} { "type": "payout.requires_approval", "id": "evt_ctc0bit3iqh25ihhl1bg", "object": "event", "created_at": "2024-12-10T09:11:39.659702396Z", "data": { "created_at": "2024-12-10T09:11:37.418151Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "INGBAU2SXXX" }, "account_number": "1234675423679987", "bank_name": "Central Bank", "country": "US", "currency": "SGD" }, "type": "bank" }, "phone": { "calling_code": "1" }, "name": "aaaaa", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "SGD", "amount": 1000 }, "final": { "currency": "SGD", "amount": 1000 }, "id": "fx_ctc0bidpk5p8ci8rf57g", "object": "fx_transaction", "exchange_rate": 1 }, "type": "swift", "status": "requires_approval", "charge_type": "ours", "purpose": "PYR001", "id": "pot_ctc0bidf9sjsk2si3qpg", "holding_currency": "AUD", "currency": "SGD", "beneficiary": "bnf_crqfjhsbvd1o6tv0gku0", "object": "payout", "statement_descriptor": "Muskan", "on_behalf_of": "ent_csorc2c1kl1roj58r2hg", "amount": 1000, "local": { "fund_transfer_network": "ach" }, "logistics_tracking_details": [], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 1000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctc0bidf9sjsk2si3qp5" } } ``` ### payout.failed ```json expandable theme={null} { "type": "payout.failed", "id": "evt_ctc145tvggacf0fci0a0", "object": "event", "created_at": "2024-12-10T10:04:07.654463614Z", "data": { "tracking_details": { "tracking_number": "67543890", "tracking_type": "utr" }, "created_at": "2024-12-10T09:15:59.251488Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "INGBAU2SXXX" }, "account_number": "1234562787358912", "bank_name": "Central Bank", "country": "US", "currency": "SGD" }, "type": "bank" }, "phone": { "calling_code": "1" }, "name": "Roman", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "SGD", "amount": 100 }, "final": { "currency": "SGD", "amount": 100 }, "id": "fx_ctc0djtpk5p8ci8rf700", "object": "fx_transaction", "exchange_rate": 1 }, "type": "swift", "status_description": "PO1008 entity_approval_rejected", "status": "failed", "charge_type": "ours", "purpose": "PYR003", "id": "pot_ctc0djtf9sjsk2si3uf0", "holding_currency": "AUD", "currency": "SGD", "beneficiary": "bnf_crqfjhsbvd1o6tv0gku0", "object": "payout", "statement_descriptor": "Muskan", "on_behalf_of": "ent_ct2ovl9f5lhf6huap5cg", "amount": 100, "local": { "fund_transfer_network": "ach" }, "logistics_tracking_details": [], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 100, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctc0djtf9sjsk2si3uf1" "failure": { "code" : "PF000000", "description": "Generic fallback, the reason of failure cannot be specified" } } } ``` ### payout.cancelled ```json expandable theme={null} { "type": "payout.cancelled", "id": "evt_ctgjf5ncu42kd3rmm3r0", "object": "event", "created_at": "2024-12-17T08:34:30.98072183Z", "data": { "created_at": "2024-12-17T08:33:48.059177Z", "beneficiary_details": { "address": { "line1": "MG Road", "line2": "Adj ST Mary School", "postal_code": "10038", "city": "Delhi", "state": "Delhi", "country": "IN" }, "destination_details": { "bank": { "bank_codes": { "aba_code": "123478789", "swift_code": "INGBAU2SXXX" }, "account_number": "1234456775333", "bank_name": "CityBank", "country": "US", "currency": "USD" }, "type": "bank" }, "phone": { "calling_code": "1", "number": "12312312312" }, "name": "Test 7", "email": "test@example.com", "type": "individual", "tax_id": "1234123" }, "payout_fx_transaction": { "initial": { "currency": "USD", "amount": 100000 }, "final": { "currency": "USD", "amount": 100000 }, "id": "fx_ctgjeqtpk5p8ci903jcg", "object": "fx_transaction", "exchange_rate": 1 }, "type": "local", "status": "cancelled", "purpose": "PYR001", "id": "pot_ctgjeqvg9n1vh5nsb3ng", "holding_currency": "AUD", "currency": "USD", "beneficiary": "bnf_crv5o44fd64iheof2r70", "object": "payout", "statement_descriptor": "erf", "on_behalf_of": "ent_ctdv4tt97ubkibq2km2g", "amount": 100000, "local": { "fund_transfer_network": "ach" }, "logistics_tracking_details": [], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 100000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctgjeqvg9n1vh5nsb3n7" } } ``` ### payout.reversed ```json expandable theme={null} { "type": "payout.reversed", "id": "evt_d4a2b7o1l435sdu92340", "object": "event", "created_at": "2025-12-19T10:15:45.123456789Z", "data": { "created_at": "2025-12-19T09:45:25.120050Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "INGBAU2SXXX" }, "account_number": "1234567890", "bank_name": "Central Bank", "country": "US", "currency": "USD" }, "type": "bank" }, "phone": { "calling_code": "1" }, "name": "John Doe", "email": "john@example.com", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "USD", "amount": 100000 }, "final": { "currency": "USD", "amount": 100000 }, "id": "fx_d4a2b705ha8onnfg24s0", "object": "fx_transaction", "exchange_rate": 1 }, "type": "swift", "status": "reversed", "charge_type": "ours", "purpose": "PYR001", "id": "pot_d4a2b76hi567m07e7q40", "holding_currency": "USD", "currency": "USD", "beneficiary": "bnf_cs8bf4m6rf9979b4isq0", "object": "payout", "balance_transaction": "btr_d4a2b7ehi567m07e7q80", "reversal_balance_transaction": "btr_d4a2b8ehi567m07e7r90", "logistics_tracking_details": [], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 100000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_d4a2b76hi567m07e7q3y" } } ``` ### payout.requires\_action ```json expandable theme={null} { "type": "payout.requires_action", "id": "evt_ctgll361mt84a8u1dvgg", "object": "event", "created_at": "2024-12-17T11:03:41.089728899Z", "data": { "tracking_details": { "tracking_number": "566975432", "tracking_type": "utr" }, "created_at": "2024-12-17T08:42:14.107051Z", "beneficiary_details": { "address": { "line1": "MG Road", "line2": "Adj ST Mary School", "postal_code": "10038", "city": "Delhi", "state": "Delhi", "country": "IN" }, "destination_details": { "bank": { "bank_codes": { "aba_code": "123478789", "swift_code": "INGBAU2SXXX" }, "account_number": "Test7", "bank_name": "CityBank", "country": "US", "currency": "USD" }, "type": "bank" }, "phone": { "calling_code": "1", "number": "12312312312" }, "name": "Roman", "email": "test@example.com", "type": "individual", "tax_id": "911-92-3333", "is_doc_verification_required": true, "verification_status": "requires_action", "status": "active", "name_local": "", "national_identification_number": "", "party_classification": "third_party", "registration_number": "" }, "payout_fx_transaction": { "initial": { "currency": "USD", "amount": 1000 }, "final": { "currency": "USD", "amount": 1000 }, "id": "fx_ctgjipdpk5p8ci903nt0", "object": "fx_transaction", "exchange_rate": 1 }, "type": "local", "status": "requires_action", "purpose": "PYR003", "id": "pot_ctgjipfg9n1vh5nsbcug", "holding_currency": "USD", "currency": "USD", "beneficiary": "bnf_crv5o44fd64iheof2r70", "object": "payout", "statement_descriptor": "Muskan", "balance_transaction": "btr_ctgjipng9n1vh5nsbd20", "on_behalf_of": "ent_ctc0kk9sgkgeelcl87i0", "amount": 1000, "local": { "fund_transfer_network": "ach" }, "logistics_tracking_details": [], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 1000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctgjipfg9n1vh5nsbcu9" } } ``` ### payout.proof\_of\_payment\_generated ```json expandable theme={null} { "type": "payout.proof_of_payment_generated", "id": "evt_cv4m2bk2ojhhksnte5r0", "object": "event", "created_at": "2025-03-06T08:47:42.820264412Z", "data": { "tracking_details": { "tracking_number": "", "tracking_type": "" }, "created_at": "2025-03-06T08:46:31.535372Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "testswift" }, "account_number": "123456789", "bank_name": "test bank", "country": "SG", "currency": "SGD" }, "type": "bank" }, "phone": { "calling_code": "65" }, "name": "John Doe", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "SGD", "amount": 10000 }, "final": { "currency": "SGD", "amount": 10000 }, "id": "fx_cv4m1pr6tce7o3q54es0", "object": "fx_transaction", "exchange_rate": 1 }, "type": "swift", "status": "succeeded", "charge_type": "ours", "purpose": "PYR001", "id": "pot_cv4m1po9mkr4ca8pbu5g", "holding_currency": "USD", "currency": "SGD", "beneficiary": "bnf_cv4m1po9mkr4ca8pbu60", "object": "payout", "balance_transaction": "btr_cv4m1po9mkr4ca8pbu9g", "mt103": "{1:F01SCBLSG22AXXX0740170000}{2:I103CHASSGSGXXXXN}{3:{103:MEP}{113:NORQ}{108:SE1\n0502503040286}{111:001}{121:0c795041-3248-4dac-9c60-f0e916452bc5}}{4:\n:20:SE10502503040286\n:23B:CRED\n:32A:250304SGD4300,00\n:33B:SGD4300,00\n:50K:/7540731\nNreach Online Services Inc\n8th The Green Ste A Delaware 19901\nUNITED STATES\n:52D:/0105553026\nTAZAPAY PTE. LTD.\n7 TEMASEK BOULEVARD,20-06 SUNTEC TO\nWER ONE,SINGAPORE,ZIP 038987\n/SINGAPORE\n:57A:CHASSGSGXXX\n:59:/8830045245\nQWIKCILVER SOLUTIONS PTE. LTD.\n:70:Xoxo Day Payout on 03rd March 2025\n:71A:OUR\n-}", "amount": 10000, "local": { "fund_transfer_network": "ach" }, "logistics_tracking_details": [], "confirmation_documents": [ { "key": "mt103", "type": "application/pdf", "value": "/confirmations/pot_cv4m1po9mkr4ca8pbu5g_mt103.pdf" } ], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 10000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_cv4m1po9mkr4ca8pbu67" } } ``` ### payout.initiator\_bank\_hold ```json expandable theme={null} { "type": "payout.initiator_bank_hold", "id": "evt_ctbvv9o1l435sdu911t1", "object": "event", "created_at": "2024-12-10T09:12:11.305264108Z", "data": { "created_at": "2024-12-10T09:12:08.12005Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "bank_code": "INGBAU2SXXX", "branch_code": "INGBAU2SXXX" }, "bank_name": "Central Bank", "country": "BR", "currency": "BRL", "account_type": "savings" }, "type": "bank" }, "phone": { "calling_code": "55" }, "name": "Test1", "email": "musk@gmail.com", "type": "individual", "tax_id": "123" }, "payout_fx_transaction": { "initial": { "currency": "BRL", "amount": 10000 }, "final": { "currency": "BRL", "amount": 10000 }, "id": "fx_ctbvv905ha8onnfg24s0", "object": "fx_transaction", "exchange_rate": 1 }, "type": "local", "status": "initiator_bank_hold", "purpose": "PYR001", "id": "pot_ctbvv96hi567m07e7q40", "holding_currency": "INR", "currency": "BRL", "beneficiary": "bnf_cs8bf4m6rf9979b4isq0", "object": "payout", "balance_transaction": "btr_ctbvv9ehi567m07e7q80", "amount": 10000, "local": { "fund_transfer_network": "pix" }, "logistics_tracking_details": [ { "tracking_number": "5436789", "logistics_provider": { "name": "DHL Express", "code": "UH783" } } ], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 10000, "category": "Goods", "description": "Subscription payout" } ], "quote": "poq_ctbvv96hi567m07e7q3x", "status_description": "Triggered when the payout is placed on hold by the initiating bank for review and will be released once the transaction is cleared by the bank." } } ``` ### payout.mt103\_generated ```json expandable theme={null} { "type": "payout.mt103_generated", "id": "evt_d086g9ri9cotns8qase0", "object": "event", "created_at": "2025-04-29T05:48:23.846543614Z", "data": { "local": {}, "tracking_details": { "tracking_number": "", "tracking_type": "utr" }, "created_at": "2025-04-08T11:31:04.54606Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "57567678" }, "account_number": "678686", "bank_name": "citi", "country": "US", "currency": "AUD" }, "type": "bank" }, "phone": { "calling_code": "1" }, "name": "test", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "AUD", "amount": 78700 }, "final": { "currency": "AUD", "amount": 78700 }, "id": "fx_cvqghu3q4fulre35bvrg", "object": "fx_transaction", "exchange_rate": 1 }, "id": "pot_cvqghu1dgfht6k9a6n30", "mt103": "{1:F01SCBLSG22AXXX0740170000}{2:I103CHASSGSGXXXXN}{3:{103:MEP}{113:NORQ}{108:SE1\n0502503040286}{111:001}{121:0c795041-3248-4dac-9c60-f0e916452bc5}}{4:\n:20:SE10502503040286\n:23B:CRED\n:32A:250304SGD4300,00\n:33B:SGD4300,00\n:50K:/7540731\nNreach Online Services Inc\n8th The Green Ste A Delaware 19901\nUNITED STATES\n:52D:/0105553026\nTAZAPAY PTE. LTD.\n7 TEMASEK BOULEVARD,20-06 SUNTEC TO\nWER ONE,SINGAPORE,ZIP 038987\n/SINGAPORE\n:57A:CHASSGSGXXX\n:59:/8830045245\nQWIKCILVER SOLUTIONS PTE. LTD.\n:70:Xoxo Day Payout on 03rd March 2025\n:71A:OUR\n-}", "status": "succeeded", "charge_type": "ours", "purpose": "PYR001", "holding_currency": "INR", "currency": "AUD", "beneficiary": "bnf_cvqghu1dgfht6k9a6n3g", "balance_transaction": "btr_cvqghu1dgfht6k9a6opg", "type": "swift", "confirmation_documents": [ { "key": "mt103", "type": "string", "value": "{1:F01SCBLSG22AXXX0740170000}{2:I103CHASSGSGXXXXN}{3:{103:MEP}{113:NORQ}{108:SE1\n0502503040286}{111:001}{121:0c795041-3248-4dac-9c60-f0e916452bc5}}{4:\n:20:SE10502503040286\n:23B:CRED\n:32A:250304SGD4300,00\n:33B:SGD4300,00\n:50K:/7540731\nNreach Online Services Inc\n8th The Green Ste A Delaware 19901\nUNITED STATES\n:52D:/0105553026\nTAZAPAY PTE. LTD.\n7 TEMASEK BOULEVARD,20-06 SUNTEC TO\nWER ONE,SINGAPORE,ZIP 038987\n/SINGAPORE\n:57A:CHASSGSGXXX\n:59:/8830045245\nQWIKCILVER SOLUTIONS PTE. LTD.\n:70:Xoxo Day Payout on 03rd March 2025\n:71A:OUR\n-}" } ], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 78700, "category": "Goods", "description": "Subscription payout" } ], "amount": 78700 } } ``` ### payout.mt199\_generated ```json expandable theme={null} { "type": "payout.mt199_generated", "id": "evt_d086g9ri9cotns8qase0", "object": "event", "created_at": "2025-04-29T05:48:23.846543614Z", "data": { "local": {}, "tracking_details": { "tracking_number": "", "tracking_type": "utr" }, "created_at": "2025-04-08T11:31:04.54606Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "57567678" }, "account_number": "678686", "bank_name": "citi", "country": "US", "currency": "AUD" }, "type": "bank" }, "phone": { "calling_code": "1" }, "name": "test", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "AUD", "amount": 78700 }, "final": { "currency": "AUD", "amount": 78700 }, "id": "fx_cvqghu3q4fulre35bvrg", "object": "fx_transaction", "exchange_rate": 1 }, "id": "pot_cvqghu1dgfht6k9a6n30", "mt103": "{1:F01SCBLSG22AXXX0740170000}{2:I103CHASSGSGXXXXN}{3:{103:MEP}{113:NORQ}{108:SE1\n0502503040286}{111:001}{121:0c795041-3248-4dac-9c60-f0e916452bc5}}{4:\n:20:SE10502503040286\n:23B:CRED\n:32A:250304SGD4300,00\n:33B:SGD4300,00\n:50K:/7540731\nNreach Online Services Inc\n8th The Green Ste A Delaware 19901\nUNITED STATES\n:52D:/0105553026\nTAZAPAY PTE. LTD.\n7 TEMASEK BOULEVARD,20-06 SUNTEC TO\nWER ONE,SINGAPORE,ZIP 038987\n/SINGAPORE\n:57A:CHASSGSGXXX\n:59:/8830045245\nQWIKCILVER SOLUTIONS PTE. LTD.\n:70:Xoxo Day Payout on 03rd March 2025\n:71A:OUR\n-}", "status": "succeeded", "charge_type": "ours", "purpose": "PYR001", "holding_currency": "INR", "currency": "AUD", "beneficiary": "bnf_cvqghu1dgfht6k9a6n3g", "balance_transaction": "btr_cvqghu1dgfht6k9a6opg", "type": "swift", "confirmation_documents": [ { "key": "mt103", "type": "string", "value": "{1:F01SCBLSG22AXXX0740170000}{2:I103CHASSGSGXXXXN}{3:{103:MEP}{113:NORQ}{108:SE1\n0502503040286}{111:001}{121:0c795041-3248-4dac-9c60-f0e916452bc5}}{4:\n:20:SE10502503040286\n:23B:CRED\n:32A:250304SGD4300,00\n:33B:SGD4300,00\n:50K:/7540731\nNreach Online Services Inc\n8th The Green Ste A Delaware 19901\nUNITED STATES\n:52D:/0105553026\nTAZAPAY PTE. LTD.\n7 TEMASEK BOULEVARD,20-06 SUNTEC TO\nWER ONE,SINGAPORE,ZIP 038987\n/SINGAPORE\n:57A:CHASSGSGXXX\n:59:/8830045245\nQWIKCILVER SOLUTIONS PTE. LTD.\n:70:Xoxo Day Payout on 03rd March 2025\n:71A:OUR\n-}" } ], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 78700, "category": "Goods", "description": "Subscription payout" } ], "amount": 78700 } } ``` ### payout.firc\_generated ```json expandable theme={null} { "type": "payout.mt199_generated", "id": "evt_d086g9ri9cotns8qase0", "object": "event", "created_at": "2025-04-29T05:48:23.846543614Z", "data": { "local": {}, "tracking_details": { "tracking_number": "", "tracking_type": "utr" }, "created_at": "2025-04-08T11:31:04.54606Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "57567678" }, "account_number": "678686", "bank_name": "HDFC", "country": "IN", "currency": "INR" }, "type": "bank" }, "phone": { "calling_code": "1" }, "name": "test", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "INR", "amount": 78700 }, "final": { "currency": "INR", "amount": 78700 }, "id": "fx_cvqghu3q4fulre35bvrg", "object": "fx_transaction", "exchange_rate": 1 }, "id": "pot_cvqghu1dgfht6k9a6n30", "mt103": "", "status": "succeeded", "charge_type": "", "purpose": "PYR001", "holding_currency": "INR", "currency": "INR", "beneficiary": "bnf_cvqghu1dgfht6k9a6n3g", "balance_transaction": "btr_cvqghu1dgfht6k9a6opg", "type": "local", "confirmation_documents": [ { "key": "firc", "type": "url", "value": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_ct2ovlfvfes2ls2icfig/kyb_doc96573_26November2024_Screenshot%202024-11-26%20at%202.31.42%20PM.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAUGJYD3OSULG77W43%2F20241210%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20241210T100403Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEM7%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0xIkcwRQIgSy1gj4k2zToD2pZE1PSMWAY70e2nKcroRpipB4S4ImECIQCEeblV2ql1kb3PXqgB%2FU8upPkQyqMLqSh1KmsWGHhCPCr9AwiH%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDI4ODQxNzM3MzA5MyIM4ZfXfG6g3ceTQd2XKtED44GmL%2FOCSPsHUdqVeBsPjh%2FW4%2Bksc5fleV7%2FA3Aoy%2FRo8teNG5xFjmU%2FWpBJ0cgZuoJJnVhyMrPnqZIBm%2BIst6u80PPxwdUYEYgv4hI7%2B24lTEoeiNYjFIwSPeMkAx%2BRtyzilTFzMOnIUD4QLn%2B%2FP7U96c0JUHw8DNImaG8OajPTV8OtxW0S0HWdO%2FsbrviEv4bOQMhWo9m2%2BvWHibILNLGh6FeTtVC2fTddRhtMuPpJKtUnbFLf4%2F%2B7x2RXi%2BwRyT7X%2FOUl4V9Hs%2F9FDwZhiDSr3xKKEOzlDgEmSBQpWDlV7XtevPn%2FEpQ3QnDyQcSPhLg6BxuZpjElf%2FSaPsKdZbt2XynisR87S6pfsEESLRFHbv68ARGDy7cnO2x%2Fif9bzgFE31M4Y74EjHnNV%2Fc1%2F%2FSg5KxRedCZ35IW%2BE9R9geeAVp5DI7FcoSYibkgseoF2Ysr903Mg9KWjQrI4vqUsgSsV6nAJC%2FiAwQZDVGOUQyfAJn1SxQpcIDnTWwBnbJcB7GS1HPuMlg0%2FMvM%2FJDXTmgPsSCPmFjhmsjVypIbSV2YjKQiPOvEJYAGn54IdkkhtohIUa5jR0%2FTDkOLDXWzkG279LpebCwFug92bFFaES8zMPS137oGOqUBF8I%2BhtHyPcwLIei2om2Wa8tXua2SSBauLK2kcvVFz7r7Syk7ZUWqMVZUPibolxSxnH1P5lrsbWbpuG4kJj5qOCyWm6v8MHMQ%2FkUFewvJ8bL6xTeOub1N8cr2WnjkfXpmYvoV70amooUPUJ0HRw%2FYMVTJXJhMJ0r2HyZYnFLz%2B14VPgRufOTdgz28YhY%2BYslIjv8OLvlGCVR0AkPwColVc9ZaqPY2&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B&response-content-type=image%2Fpng&x-id=GetObject&X-Amz-Signature=f9df595274faec769a77a7712a87954db65003702ea055782404fdd75a3fdcd1" } ], "amount": 78700 } } ``` ### payout.other\_document\_generated ```json expandable theme={null} { "type": "payout.other_document_generated", "id": "evt_d086g9ri9cotns8qase0", "object": "event", "created_at": "2025-04-29T05:48:23.846543614Z", "data": { "local": {}, "tracking_details": { "tracking_number": "", "tracking_type": "utr" }, "created_at": "2025-04-08T11:31:04.54606Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "57567678" }, "account_number": "678686", "bank_name": "HDFC", "country": "IN", "currency": "INR" }, "type": "bank" }, "phone": { "calling_code": "1" }, "name": "test", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "INR", "amount": 78700 }, "final": { "currency": "INR", "amount": 78700 }, "id": "fx_cvqghu3q4fulre35bvrg", "object": "fx_transaction", "exchange_rate": 1 }, "id": "pot_cvqghu1dgfht6k9a6n30", "mt103": "", "status": "succeeded", "charge_type": "", "purpose": "PYR001", "holding_currency": "INR", "currency": "INR", "beneficiary": "bnf_cvqghu1dgfht6k9a6n3g", "balance_transaction": "btr_cvqghu1dgfht6k9a6opg", "type": "local", "confirmation_documents": [ { "key": "abc", // abc is Other document type "type": "url", "value": "https://s3.ap-southeast-1.amazonaws.com/tazapay-onboarding-service/kyb_ct2ovlfvfes2ls2icfig/kyb_doc96573_26November2024_Screenshot%202024-11-26%20at%202.31.42%20PM.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAUGJYD3OSULG77W43%2F20241210%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20241210T100403Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEM7%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0xIkcwRQIgSy1gj4k2zToD2pZE1PSMWAY70e2nKcroRpipB4S4ImECIQCEeblV2ql1kb3PXqgB%2FU8upPkQyqMLqSh1KmsWGHhCPCr9AwiH%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDI4ODQxNzM3MzA5MyIM4ZfXfG6g3ceTQd2XKtED44GmL%2FOCSPsHUdqVeBsPjh%2FW4%2Bksc5fleV7%2FA3Aoy%2FRo8teNG5xFjmU%2FWpBJ0cgZuoJJnVhyMrPnqZIBm%2BIst6u80PPxwdUYEYgv4hI7%2B24lTEoeiNYjFIwSPeMkAx%2BRtyzilTFzMOnIUD4QLn%2B%2FP7U96c0JUHw8DNImaG8OajPTV8OtxW0S0HWdO%2FsbrviEv4bOQMhWo9m2%2BvWHibILNLGh6FeTtVC2fTddRhtMuPpJKtUnbFLf4%2F%2B7x2RXi%2BwRyT7X%2FOUl4V9Hs%2F9FDwZhiDSr3xKKEOzlDgEmSBQpWDlV7XtevPn%2FEpQ3QnDyQcSPhLg6BxuZpjElf%2FSaPsKdZbt2XynisR87S6pfsEESLRFHbv68ARGDy7cnO2x%2Fif9bzgFE31M4Y74EjHnNV%2Fc1%2F%2FSg5KxRedCZ35IW%2BE9R9geeAVp5DI7FcoSYibkgseoF2Ysr903Mg9KWjQrI4vqUsgSsV6nAJC%2FiAwQZDVGOUQyfAJn1SxQpcIDnTWwBnbJcB7GS1HPuMlg0%2FMvM%2FJDXTmgPsSCPmFjhmsjVypIbSV2YjKQiPOvEJYAGn54IdkkhtohIUa5jR0%2FTDkOLDXWzkG279LpebCwFug92bFFaES8zMPS137oGOqUBF8I%2BhtHyPcwLIei2om2Wa8tXua2SSBauLK2kcvVFz7r7Syk7ZUWqMVZUPibolxSxnH1P5lrsbWbpuG4kJj5qOCyWm6v8MHMQ%2FkUFewvJ8bL6xTeOub1N8cr2WnjkfXpmYvoV70amooUPUJ0HRw%2FYMVTJXJhMJ0r2HyZYnFLz%2B14VPgRufOTdgz28YhY%2BYslIjv8OLvlGCVR0AkPwColVc9ZaqPY2&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B&response-content-type=image%2Fpng&x-id=GetObject&X-Amz-Signature=f9df595274faec769a77a7712a87954db65003702ea055782404fdd75a3fdcd1" } ], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 78700, "category": "Goods", "description": "Subscription payout" } ], "amount": 78700 } } ``` ### payout.compliance\_hold ```json expandable theme={null} { "type": "payout.compliance_hold", "id": "evt_d3n3iavvima100lp71kg", "object": "event", "created_at": "2025-10-14T11:51:07.422226364Z", "data": { "local": {}, "created_at": "2025-10-14T11:50:56.075199Z", "beneficiary_details": { "destination_details": { "bank": { "bank_codes": { "swift_code": "sw32432" }, "account_number": "3423435427899", "bank_name": "Central Bank", "country": "CN", "currency": "CNY" }, "type": "bank" }, "name": "Allen", "type": "business" }, "payout_fx_transaction": { "initial": { "currency": "CNY", "amount": 10000 }, "final": { "currency": "CNY", "amount": 10000 }, "id": "fx_d3n3i7tfs5v4tkcn6ktg", "object": "fx_transaction", "exchange_rate": 1 }, "purpose": "PYR004", "status": "compliance_hold", "charge_type": "ours", "id": "pot_d3n3i7t2amni271p7qd0", "holding_currency": "EUR", "currency": "CNY", "beneficiary": "bnf_d3n3hrl2amni271p7q8g", "transaction_description": "asd", "balance_transaction": "btr_d3n3i852amni271p7qh0", "type": "swift", "holding_fx_quote": "fx_d3n3i7tfs5v4tkcn6ku0", "destination_fx_quote": "fx_d3n3i7tfs5v4tkcn6ktg", "documents": [ { "id": "doc_d3n3i852amni271p7qdg", "type": "invoice", "url": "https://s3.ap-southeast-1.amazonaws.com/tazapay-payout-document-qa/pot_d3n3i7t2amni271p7qd0" } ], "amount": 10000, "quote": "poq_d3n3i7t2amni271p7qd9", "logistics_tracking_details": [], "confirmation_documents": [], "items": [ { "name": "Premium subscription (Jan 2026)", "quantity": 1, "amount": 10000, "category": "Goods", "description": "Subscription payout" } ] } } ``` ### payout.gpi\_tracking ```json expandable theme={null} { "type": "payout.gpi_tracking", "id": "evt_gpi_123", "object": "event", "created_at": "2025-11-28T10:12:01Z", "data": { "id": "pot_123", "object": "payout", "type": "swift", "status": "succeeded", "tracking_details": { "tracking_type": "uetr", "tracking_number": "11111111-2222-3333-4444-555555555555" }, "gpi": { "latest": { "reasonCode": "ACCC", "statusDescription": "Funds credited to beneficiary account - AAAABBCC123", "timestamp": "2025-11-28T16:20:00Z" }, "timeline": [ { "reasonCode": "ACCC", "statusDescription": "Funds credited to beneficiary account - AAAABBCC123", "timestamp": "2025-11-28T16:20:00Z" }, { "reasonCode": "ACSC", "statusDescription": "Funds received by beneficiary bank - AAAABBCC123", "timestamp": "2025-11-28T15:38:10Z" }, { "reasonCode": "ACSP/G004", "statusDescription": "In transit – processing with correspondent bank - AAAABBCC123", "timestamp": "2025-11-28T14:00:00Z" }, { "reasonCode": "ACSP/G003", "statusDescription": "In transit – processing with correspondent bank - AAAABBCC123", "timestamp": "2025-11-28T13:00:00Z" }, { "reasonCode": "ACSP/G002", "statusDescription": "In transit – processing with correspondent bank - AAAABBCC123", "timestamp": "2025-11-28T12:00:00Z" }, { "reasonCode": "ACSP/G001", "statusDescription": "In transit – sent to non-tracked bank (further updates unavailable) - AAAABBCC123", "timestamp": "2025-11-28T11:05:00Z" }, { "reasonCode": "ACSP/G000", "statusDescription": "In transit – with intermediary bank - AAAABBCC123", "timestamp": "2025-11-28T10:10:40Z" } ] } } } ``` For full schema, status codes, and edge cases, see [SWIFT GPI Tracking](/api-reference/tazapay-api/swift-gpi-tracking). # Phone Object Source: https://developer.tazapay.com/api-reference/tazapay-api/phone-object ## Object Structure ```json Phone theme={null} { "calling_code": "91", "number": "9231231231" } ``` ## Object Parameters | Field | Type | Description | | :------------ | :----- | :-------------------------------------------------------------- | | calling\_code | string | The international calling code for the customer's phone number. | | number | string | The phone number of the customer. | # Refund Source: https://developer.tazapay.com/api-reference/tazapay-api/refund A Tazapay API object that is used to return money to a customer after a payment has been made. It simplifies the process of issuing refunds for products or services, helping businesses maintain customer satisfaction. ## Object Structure ```json JSON expandable theme={null} { "id": "rfd_afiuabfia23wifaiofnioa12nfianf", "object": "refund", "payin": "chk_cirsp2sl4ar024j0akj0", "amount": 90000, "currency": "USD", "customer_receives": { "currency": "SGD", "amount": 133200 }, "payment_attempt": "pat_ahbfiuahfiuaiofnioain", "reason": "Damaged Goods", "metadata": { "key1": "value1", "key2": "value2" }, "status": "succeeded", "status_description": "", "webhook_url": "https://mystore.webhook.tazapay.refund/", "created_at": "2023-07-23 23:59:56" } ``` ## Parameters ### Refund | Field | Subfield | Type | Description | | :------------------ | :------- | :--------------------- | :------------------------------------------------------------------------------------------------------ | | id | | string | The unique Tazapay identifier for the refund. | | object | | string | The type of object, which is "refund". | | payin | | string | The unique Tazapay ID of the related payin transaction. | | amount | | number | The total amount being refunded. | | currency | | string | The currency in which the refund was made (e.g., USD). | | customer\_receives | | object | The amount and currency received by the customer after the refund. | | | currency | string | The currency in which the customer receives the refund. | | | amount | number | The amount the customer receives after the refund. | | payment\_attempt | | string | The unique Tazapay ID of the payment attempt associated with the refund. | | reason | | string | The reason for the refund (e.g., "Damaged Goods"). | | metadata | | json | Set of key-value pairs attached to the refund object. | | status | | enum | The current status of the refund \[Values - Requested, Pending, Initiated, Succeeded, Failed, Rejected] | | status\_description | | string | A description of the current refund status. | | webhook\_url | | string | The URL for webhook notifications related to the refund. | | created\_at | | string (ISO timestamp) | The timestamp when the refund was created. | # Initiate Refund Source: https://developer.tazapay.com/api-reference/tazapay-api/refund-api post /v3/refund To initiate a refund of an existing paid transaction back to source **Not all the payment methods support refunds!** Depending on the payment method, Tazapay may not be able to process refunds. For more info, read our [FAQ](https://support.tazapay.com/what-payment-methods-are-unsupported-for-refunds) * For refunding a payment made by Promptpay, WeChat, Linepay, Shopeepay and Truemoney in Thailand, the customer's phone number is required. You can choose to pass it to Tazapay in the customer\_details field of the checkout API. You can also use the Update Customer endpoint to attach the phone number to an existing customer you want to refund. # Fetch Refund Source: https://developer.tazapay.com/api-reference/tazapay-api/refund-status-api get /v3/refund/{id} This endpoint fetches the details of an already existing refund object. # Refund Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/refund-webhooks ## refund.status specific events: These are the events created and triggered when the status of the refund object changes. | Event | Description | Default (on/off) | | :--------------- | :--------------------------------------- | :--------------- | | refund.succeeded | When a refund has succeeded | On | | refund.failed | When a refund fails | On | | refund.pending | When a refund is pending to be processed | On | ### **refund.pending** ```json JSON expandable theme={null} { "type": "refund.pending", "created_at": "2023-07-23T23:59:56.000000Z", "data": { "id": "rfd_ahfafooi7ibakbfahoan", "object": "refund", "payin": "chk_cirsp2sl4ar024j0akj0", "amount": 90000, "currency": "USD", "customer_receives": { "currency": "SGD", "amount": 133200 }, "payment_attempt": "pat_ahbfiuahfiuaiofnioain", "reason": "Damaged Goods", "status": "pending", "status_reason": "", "holding_currency": "USD", "balance_transaction": "", "reference_id": "order_12345", "webhook_url": "https://mystore.webhook.tazapay.refund/", "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2023-07-23T23:59:56.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### **refund.succeeded** ```json JSON expandable theme={null} { "type": "refund.succeeded", "created_at": "2023-07-24T00:05:12.000000Z", "data": { "id": "rfd_ahfafooi7ibakbfahoan", "object": "refund", "payin": "chk_cirsp2sl4ar024j0akj0", "amount": 90000, "currency": "USD", "customer_receives": { "currency": "SGD", "amount": 133200 }, "payment_attempt": "pat_ahbfiuahfiuaiofnioain", "reason": "Damaged Goods", "status": "succeeded", "status_reason": "", "holding_currency": "USD", "balance_transaction": "btr_d679f6dqd9ne66lsngb0", "reference_id": "order_12345", "webhook_url": "https://mystore.webhook.tazapay.refund/", "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2023-07-23T23:59:56.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### **refund.failed** ```json JSON expandable theme={null} { "type": "refund.failed", "created_at": "2023-07-24T00:05:12.000000Z", "data": { "id": "rfd_ahfafooi7ibakbfahoan", "object": "refund", "payin": "chk_cirsp2sl4ar024j0akj0", "amount": 90000, "currency": "USD", "customer_receives": { "currency": "SGD", "amount": 133200 }, "payment_attempt": "pat_ahbfiuahfiuaiofnioain", "reason": "Damaged Goods", "status": "failed", "status_reason": "Refund could not be processed", "holding_currency": "USD", "balance_transaction": "", "reference_id": "order_12345", "webhook_url": "https://mystore.webhook.tazapay.refund/", "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2023-07-23T23:59:56.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ## Other events: | Event | Description | Default (on/off) | | :------------- | :---------------------------------------------- | :--------------- | | refund.created | When a refund object is created for the account | On | ### **refund.created** ```json JSON expandable theme={null} { "type": "refund.created", "created_at": "2023-07-23T23:59:56.000000Z", "data": { "id": "rfd_ahfafooi7ibakbfahoan", "object": "refund", "payin": "chk_cirsp2sl4ar024j0akj0", "amount": 90000, "currency": "USD", "customer_receives": { "currency": "SGD", "amount": 133200 }, "payment_attempt": "pat_ahbfiuahfiuaiofnioain", "reason": "Damaged Goods", "status": "requested", "status_reason": "", "holding_currency": "USD", "balance_transaction": "", "reference_id": "order_12345", "webhook_url": "https://mystore.webhook.tazapay.refund/", "metadata": { "key1": "value1", "key2": "value2" }, "created_at": "2023-07-23T23:59:56.000000Z" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` # Simulating Verifications on Test Environment (Sandbox) Source: https://developer.tazapay.com/api-reference/tazapay-api/sandbox-simulation Tazamatch is available in [sandbox](https://dashboard-sandbox.tazapay.com/) by default. To test different verification scenarios, pass the account number / IBAN values shown below to `POST /v3/verify/payee` (with any name - name does not drive the outcome - and the BIC / sort code shown where applicable). Country and currency have no effect on sandbox behaviour; only the account number / IBAN drives the response. ## Match outcomes For the corresponding account number / IBAN, the outcomes would be same as below. | Use it to test | Account / IBAN | verification\_status | match\_outcome | match\_score | beneficiary\_type | account\_exists | | ------------------------------------------------ | ------------------------------- | -------------------- | -------------- | ------------ | ----------------- | --------------- | | Strong match - IBAN (IE) | `IE83AIBK93115200000001` | valid | strong\_match | 1.00 | individual | true | | Strong match - Account+BIC (IN) | `987654321001` | valid | strong\_match | 1.00 | individual | true | | Strong match - Account+BIC (NG) | `1234567890` | valid | strong\_match | 1.00 | individual | true | | Strong match - Account+Sort Code (GB) | `12345678` | valid | strong\_match | 1.00 | individual | true | | Strong match - Account+Routing (US) | `781245633` | valid | strong\_match | 1.00 | individual | true | | Strong match - Account only (MX) | `999000000000000505` | valid | strong\_match | 1.00 | individual | true | | Strong match - Account only (AR) | `0170032450000643500000` | valid | strong\_match | 1.00 | individual | true | | Strong match - Registration ID (CN, individual) | `321872160000` | valid | strong\_match | 1.00 | individual | true | | Strong match - Registration ID (CN, business) | `321872160001` | valid | strong\_match | 1.00 | business | true | | Strong match - Registration ID (BR, business) | `BR1199950505000010000000888C1` | valid | strong\_match | 1.00 | business | true | | Strong match - Registration ID (SA, business) | `SA1510100011100000461311` | valid | strong\_match | 1.00 | business | true | | Strong match - IBAN (DE) | `DE67370400440532010001` | valid | strong\_match | 1.00 | individual | true | | Strong match - IBAN (NL) | `NL80ABNA0513165301` | valid | strong\_match | 1.00 | individual | true | | Strong match - IBAN (ES) | `ES0721000418450200051001` | valid | strong\_match | 1.00 | individual | true | | Strong match - Korean corridor (translated name) | `11112222321` | valid | strong\_match | 0.95 | individual | true | | Partial match - IBAN (IE) | `IE56AIBK93115200000002` | valid | partial\_match | 0.50 | individual | true | | Partial match - Account+Sort Code (GB) | `23456789` | valid | partial\_match | 0.50 | individual | true | | Partial match - Account+Routing (US) | `781245634` | valid | partial\_match | 0.50 | individual | true | | Partial match - Registration ID (CN) | `321872160003` | valid | partial\_match | 0.50 | individual | true | | Partial match - Registration ID (CN, alt) | `321872160004` | valid | partial\_match | 0.50 | individual | true | | No Match - IBAN (IE) | `IE29AIBK93115200000003` | invalid | no\_match | 0.00 | individual | true | | No Match - Account+Routing (US) | `781245636` | invalid | no\_match | 0.00 | individual | true | | No Match - Account+Sort Code (GB) | `34567890` | invalid | no\_match | 0.00 | individual | true | ## account\_exists variants | Use it to test | Account / IBAN | verification\_status | match\_outcome | match\_score | beneficiary\_type | account\_exists | | -------------------------------------------------- | ------------------------ | -------------------- | -------------- | ------------ | ----------------- | --------------- | | Strong match, `account_exists = true` | `987654321001` | valid | strong\_match | 1.00 | individual | true | | Strong match, `account_exists = false` | `987654321006` | valid | strong\_match | 1.00 | individual | false | | Strong match, `account_exists` not returned (null) | `987654321007` | valid | strong\_match | 1.00 | individual | null | | Account closed | `IE45AIBK93115200000006` | invalid | n/a | n/a | n/a | false | ## beneficiary\_type not returned | Use it to test | Account / IBAN | verification\_status | match\_outcome | match\_score | beneficiary\_type | account\_exists | | -------------------------------------------- | ------------------------ | -------------------- | -------------- | ------------ | ----------------- | --------------- | | Strong match, `beneficiary_type = null` (DE) | `DE67370400440532010007` | valid | strong\_match | 1.00 | null | true | | Strong match, `beneficiary_type = null` (IN) | `987654321008` | valid | strong\_match | 1.00 | null | true | ## matched\_name\_details - corrected & translated name | Use it to test | Account / IBAN | match\_outcome | match\_score | corrected\_name | translated\_name | | ------------------------------------------ | -------------- | -------------- | ------------ | ------------------ | ---------------- | | Corrected name returned (partial match) | `123456789007` | partial\_match | 0.80 | SACHIN TENDULKAR | n/a | | Translated name returned (Korean corridor) | `11112222321` | strong\_match | 0.95 | n/a | Song Hye-kyo | | Corrected name returned (GB, strong match) | `12345678` | strong\_match | 1.00 | HARRY SNAPE POTTER | n/a | `corrected_name` is the suggested correct name; surface it to the payer for confirmation. `translated_name` is relevant for cross-script corridors (Korean, Chinese, Arabic). ## additional\_information - transaction activity | Use it to test | Account / IBAN | match\_outcome | match\_score | transaction\_activity | transaction\_activity\_started\_at | | ---------------------------------------- | ------------------------ | -------------- | ------------ | --------------------- | ---------------------------------- | | Transaction activity = true | `987654321009` | strong\_match | 1.00 | true | 2026-01-01 | | Transaction activity = false | `1234567891` | strong\_match | 1.00 | false | 2026-01-01 | | Transaction activity not returned (null) | `DE67370400440532010008` | strong\_match | 1.00 | null | null | `transaction_activity = false` does not mean the account is inactive; it means no recent transaction activity was detected in the observed time period. A "returned false" case is only distinguishable from "not returned" when `transaction_activity_started_at` also accompanies it - the response omits the `transaction_activity_details` block entirely unless one of the two fields is present. ## Combined scenarios Multiple `verified_information` fields returned together in a single response. All rows have `verification_status = valid`. | Use it to test | Account / IBAN | match\_outcome | match\_score | beneficiary\_type | account\_exists | corrected\_name | transaction\_activity | | --------------------------------------------------------------- | ------------------------ | -------------- | ------------ | ----------------- | --------------- | -------------------------------- | --------------------- | | Strong match + transaction\_activity | `IE83AIBK93115200000009` | strong\_match | 1.00 | individual | true | n/a | true | | Business strong match + transaction\_activity | `NL80ABNA0513165309` | strong\_match | 1.00 | business | true | n/a | true | | Strong match + transaction\_activity (alt) | `987654321010` | strong\_match | 1.00 | individual | true | n/a | true | | Business strong match + corrected\_name + transaction\_activity | `321872160002` | strong\_match | 1.00 | business | true | JSR APPLE AND ORANGE COMPANY LTD | true | | Partial match + corrected\_name + transaction\_activity=false | `123456789008` | partial\_match | 0.80 | individual | true | SACHIN RAMESH TENDULKAR | false | | No match + transaction\_activity=false | `IE29AIBK93115200000004` | no\_match | 0.00 | individual | true | n/a | false | | account\_exists & beneficiary\_type not returned | `DE67370400440532010009` | strong\_match | 1.00 | null | null | n/a | n/a | ## Error scenarios | Use it to test | Account / IBAN | verification\_status | Description | account\_exists | | ----------------------------------------------- | -------------------------- | -------------------- | ------------------------------------------------------- | --------------- | | Creditor account not found (IE) | `IE72AIBK93115200000005` | invalid | CreditorAccountNotFound | false | | Creditor account not found (ID) | `1234567890343` | invalid | CreditorAccountNotFound | false | | Creditor account not found (MX) | `999000000000000123` | invalid | CreditorAccountNotFound | false | | Creditor agent invalid - sort code invalid (GB) | `11223344` | invalid | CreditorAgentInvalid | n/a | | Creditor agent invalid - BIC invalid (IN) | `987654321014` | invalid | CreditorAgentInvalid | n/a | | Creditor agent invalid - BIC unrecognised (BD) | `111112222202` | invalid | CreditorAgentInvalid | n/a | | Creditor agent invalid - generic | `987654321011` | invalid | CreditorAgentInvalid | n/a | | Creditor account flagged (IN) | `987654321003` | invalid | CreditorAccountFlagged | false | | Creditor name match incomplete (IN) | `987654321005` | valid | CreditorNameMatchIncomplete | true | | Creditor account detail unable to validate (ID) | `987654321012` | not\_supported | We were unable to validate the payee for this corridor. | n/a | | Creditor account detail unable to validate (DE) | `DE29370400440532010006` | not\_supported | We were unable to validate the payee for this corridor. | n/a | | Invalid registration number (IT) | `IT129499821` | invalid | InvalidRegistrationNumber | n/a | | Account logic test successful (IE) | `IE92BOFI90001710027952` | valid | AccountLogicTestSuccessful | true | | Account logic test failure (NL) | `NL84ABNA042560090` | invalid | AccountLogicTestFailure | false | | Account closed (IE) | `IE45AIBK93115200000006` | invalid | account\_closed | false | | Currency mismatch | `0170032450000643500001` | not\_supported | currency\_mismatch | n/a | | Corrected currency | `AE350030012285049920002` | not\_supported | corrected\_currency | n/a | | Unrecognised response code | `987654321099` | failed | UnrecognisedResponseCode | n/a | | Unknown / unconfigured account | *(any unrecognised value)* | not\_supported | sandbox\_account\_not\_configured | n/a | `CreditorAccountFlagged` means the account exists but has been flagged (e.g. suspected fraud/compliance hold) - block the payment; do not expose the raw flag reason to the payer. Only an unrecognised response code returns `verification_status = failed`; `invalid` and `not_supported` are the outcomes for every documented error code above. ### HTTP error responses These two cases simulate a technical failure during verification: an HTTP error is returned, **no verification record is created, and no fee is charged** - unlike every other case on this page, which returns HTTP 200 with a persisted record. | Use it to test | Account / IBAN | HTTP response | Notes | | -------------------------------- | -------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Blank / malformed account number | *(blank)* | 500 Internal Server Error | We were unable to securely process your verification request due to an internal error. Please try again, and contact [support@tazapay.com](mailto:support@tazapay.com) if the problem persists. | | Timeout / unavailable | `404404404` | 503 Service Unavailable | Payee verification is temporarily unavailable. Please try again shortly. | # Settlement Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/settlement-webhooks ## Related Links * [Settlement Object](/api-reference/tazapay-api/settlements-1) ## Settlement Status Specific Events: These are the events created and triggered when the status of the settlement object changes. | Event | Description | Default (on/off) | | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :--------------- | | settlement.created | When the settlement is created | Off | | settlement.processing | When the settlement is initiated from Tazapay | Off | | settlement.succeeded | When the settlement reaches the destination bank account (using local rails) or is initiated from Tazapay (using the SWIFT network) | Off | | settlement.failed | When a settlement fails | Off | ### settlement.created ```json JSON expandable theme={null} { "type": "settlement.created", "created_at": "2025-04-29T12:34:56+05:30", "data": { "id": "stl_ahfafooi7ibakbfahoan", "object": "settlement", "account_id": "acc_d3inm6ami8u10oqfm", "status": "created", "status_description": "", "currency": "USD", "amount": 100123, "fee": 123, "net_amount": 100000, "type": "wire_transfer", "count": { "payins": 100, "refunds": 10, "adjustments": 25, "collects": 30, "payouts": 10 }, "tracking_details": { "tracking_number": "", "tracking_type": "" }, "mt103": null, "balance_transaction": "btr_1234", "confirmation_documents": [], "created_at": "2025-04-29T12:34:56+05:30", "updated_at": "2025-04-29T12:34:56+05:30" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### settlement.processing ```json JSON expandable theme={null} { "type": "settlement.processing", "created_at": "2025-04-29T13:00:00+05:30", "data": { "id": "stl_ahfafooi7ibakbfahoan", "object": "settlement", "account_id": "acc_d3inm6ami8u10oqfm", "status": "processing", "status_description": "", "currency": "USD", "amount": 100123, "fee": 123, "net_amount": 100000, "type": "wire_transfer", "count": { "payins": 100, "refunds": 10, "adjustments": 25, "collects": 30, "payouts": 10 }, "tracking_details": { "tracking_number": "8937589hfoiha98h", "tracking_type": "uetr" }, "mt103": null, "balance_transaction": "btr_1234", "confirmation_documents": [], "created_at": "2025-04-29T12:34:56+05:30", "updated_at": "2025-04-29T13:00:00+05:30" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### settlement.succeeded ```json JSON expandable theme={null} { "type": "settlement.succeeded", "created_at": "2025-04-30T09:15:22+05:30", "data": { "id": "stl_ahfafooi7ibakbfahoan", "object": "settlement", "account_id": "acc_d3inm6ami8u10oqfm", "status": "succeeded", "status_description": "", "currency": "USD", "amount": 100123, "fee": 123, "net_amount": 100000, "type": "wire_transfer", "count": { "payins": 100, "refunds": 10, "adjustments": 25, "collects": 30, "payouts": 10 }, "tracking_details": { "tracking_number": "8937589hfoiha98h", "tracking_type": "uetr" }, "mt103": "{1:F01BANKUS33AXXX0000000000}\n{2:O1031205050425BANKGB2LXXXX22221234560504251205N}\n{3:{108:20250408ABC12345}}\n{4:\n:20:ABC1234567890\n:23B:CRED\n:32A:250408USD100000,00\n:50K:/1234567890\nMERCHANT NAME\n123 MAIN STREET\nSINGAPORE 049483\n:59:/0987654321\nJANE SMITH\n456 ELM STREET\nLONDON SW1A 1AA\nUNITED KINGDOM\n:70:SETTLEMENT PAYMENT\n:71A:OUR\n-}\n", "balance_transaction": "btr_1234", "confirmation_documents": [], "created_at": "2025-04-29T12:34:56+05:30", "updated_at": "2025-04-30T09:15:22+05:30" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### settlement.failed ```json JSON expandable theme={null} { "type": "settlement.failed", "created_at": "2025-04-30T09:15:22+05:30", "data": { "id": "stl_ahfafooi7ibakbfahoan", "object": "settlement", "account_id": "acc_d3inm6ami8u10oqfm", "status": "failed", "status_description": "Beneficiary account details incorrect", "currency": "USD", "amount": 100123, "fee": 123, "net_amount": 100000, "type": "wire_transfer", "count": { "payins": 100, "refunds": 10, "adjustments": 25, "collects": 30, "payouts": 10 }, "tracking_details": { "tracking_number": "8937589hfoiha98h", "tracking_type": "uetr" }, "mt103": null, "balance_transaction": "btr_1234", "confirmation_documents": [], "created_at": "2025-04-29T12:34:56+05:30", "updated_at": "2025-04-30T09:15:22+05:30" }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` # Settlements Source: https://developer.tazapay.com/api-reference/tazapay-api/settlements-1 # Simulate Collection Account status on Sandbox Source: https://developer.tazapay.com/api-reference/tazapay-api/simulate-collection-account-status-in-sandbox You can create Collection Accounts in [sandbox](https://dashboard-sandbox.tazapay.com/) by default, with no separate enablement needed to start testing. In sandbox, no real transaction will be associated with this account, so it never activates on its own. When you create one, its `enable` request stays in `processing` until you simulate the next status. You control every transition, which lets you test the full lifecycle end to end: create an entity, approve it, provision a Collection Account, take it to `enabled`, and then simulate incoming payments against it. ## The flow at a glance 1. Create an entity, if you're collecting on behalf of your customers. 2. Simulate the entity status to take it to `approved`. 3. Create the Collection Account, which starts out with an `enable` request. 4. Simulate the Collection Account status to take that request to `succeeded` so the account becomes `enabled`. 5. Simulate a collect to mimic an incoming payment into the enabled account. Skip this step if the Collection Account is for your own collections. It is required only for [collections on behalf of](/collection-accounts/on-behalf-of/introduction) your customers, where the account is attributed to an entity via `on_behalf_of`. Create the entity using the [Create Entity](/api-reference/tazapay-api/create-entity) API, or from the [Sandbox dashboard](https://dashboard-sandbox.tazapay.com/) under **Entities**. A newly created entity is `pending`. Take it to `approved` before using it on a Collection Account. Full steps and the list of statuses you can simulate are on [Simulate entity status on Sandbox](/api-reference/tazapay-api/simulate-entity-status-in-sandbox). Track the transitions with [Entity Webhooks](/api-reference/tazapay-api/entity-webhook). Create the account using the [Create Collection Account](/api-reference/tazapay-api/create-collection-account) API - pass `on_behalf_of` with the entity from Step 1 if you are collecting for a customer - or from the [Sandbox dashboard](https://dashboard-sandbox.tazapay.com/) as described in [Requesting via Dashboard](/collection-accounts/requesting-for-vas/dashboard). For the account types and rails you can provision, call [Get Virtual Account Metadata](/api-reference/tazapay-api/virtual-account-metadata) or [Get Wallet Metadata](/api-reference/tazapay-api/wallet-metadata) — the accepted values are provider-configured and can change. See [Collection Accounts Payment Method Type](/api-reference/tazapay-api/collection-accounts-payment-method-type) for a static reference. The account is created with status `disabled` and an `enable` request attached: ```json Response (trimmed) theme={null} { "id": "cva_d2dgk0552psfuj1he0", "object": "collection_account", "type": "virtual_account", "payment_method_type": "local_bank_transfer_sgd", "status": "disabled", "requests": [ { "id": "cvar_dbqlkip52psfuj1heju", "object": "collection_account_request", "collection_account_id": "cva_d2dgk0552psfuj1he0", "type": "enable", "status": "processing", "status_description": "Activation in progress." } ] } ``` Note the request id (`cvar_` for a virtual account, `cwar_` for a wallet) - this is the object you simulate in the next step. The account's own `status` is never set directly; it is derived from the state of this request. For the complete lifecycle, see [Collection Account Status Flow](/collection-accounts/requesting-for-vas/api#collection-account-status-flow). In sandbox the request is not picked up by any provider, so it stays in `processing` indefinitely until you simulate it. Navigate to [**Sandbox dashboard**](https://dashboard-sandbox.tazapay.com/) **-> Collection Accounts -> Virtual Accounts / Wallets tab -> Collection Account Detail Page -> Simulate Status**, then pick the status you want the enablement request to move to. Simulate `succeeded` to get a usable account: the request is marked `succeeded`, sandbox bank or wallet details are generated, and the account status flips to `enabled`. Only then can it receive collects. You can also step through the intermediate statuses first - for example `processing` → `requires_action` → `approval_hold` → `succeeded` - to check how your integration handles each one. With the account `enabled`, fetch it to read the bank or wallet details your payer would use, then mimic an incoming payment from [**Sandbox dashboard**](https://dashboard-sandbox.tazapay.com/) **-> Virtual Accounts/Wallets -> Simulate Collect**. You can simulate every intermediate and terminal collect state, for both fiat and crypto. The complete matrix is on [Simulating Collects on Sandbox](/api-reference/tazapay-api/simulate-collects-on-sandbox). A simulated collect credits a dummy balance in your test account, which you can then use to fund and test payouts end to end. *** ## Possible values of Collection Account request status | Target status | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `processing` | The request is being processed. This is the status a newly created request starts in. | | `requires_action` | The request needs input from you, such as a supporting document. Use this to test your requires-action handling. | | `approval_hold` | The request is held pending approval. Not available for disablement requests. | | `succeeded` | The request completed. Account details are generated and the account status becomes `enabled`. Terminal. | | `failed` | The request failed permanently. The account stays `disabled`. Terminal. | | `cancelled` | The request was cancelled. The account stays `disabled`. Terminal. | `succeeded`, `failed` and `cancelled` are terminal. Once a request reaches one of them it cannot be simulated any further - create a new Collection Account to run another scenario. ## What you can and cannot simulate | Action | Sandbox behaviour | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Creating an account | Creates an `enable` request that stays in `processing`. Simulate it to reach any status above. | | Disabling an account | In sandbox this is synchronous and takes effect immediately - no request is created, so there is nothing to simulate. In production, disabling is asynchronous and does create a request; see [Update Collection Account](/api-reference/tazapay-api/update-collection-account). | | Re-enabling an account | Takes effect immediately, same as disabling. | ## Webhooks Simulated transitions behave like real ones, so point your sandbox webhook endpoint at your integration and test against the events it will receive in production: * [Collection Account Webhooks](/api-reference/tazapay-api/collection-account-webhooks) - `collection_account.creation_succeeded` fires when you simulate `succeeded` and the account becomes `enabled` * [Collect Webhooks](/api-reference/tazapay-api/collect-webhook) - fired for every state the simulated collect passes through The request-level events (`collection_account.creation_requires_action`, `creation_under_approval_hold`, `creation_failed`, `creation_cancelled`) are listed under [Upcoming Webhook Events](/api-reference/tazapay-api/collection-account-webhooks#upcoming-webhook-events) and are not delivered yet. Simulating those statuses still updates the request, which you can read back from [Get Collection Account](/api-reference/tazapay-api/get-collection-account). *** Run the whole flow on sandbox with copy-pasteable API calls. Every state a request passes through, and how the account status follows it. # Simulating Collects On Sandbox Source: https://developer.tazapay.com/api-reference/tazapay-api/simulate-collects-on-sandbox Collection Accounts are now available by default in [Sandbox](https://dashboard-sandbox.tazapay.com/). To help you test your integration seamlessly, we provide a **Collect Simulation** feature. Collect simulation allows you to mimic a successful incoming payment in your test environment without processing a real transaction. ## **Testing your collect lifecycle** You can simulate a collect transaction for all possible intermediate and terminal states. This enables you to validate that your integration correctly handles every collect scenario. Each simulated state change fires the same event your integration will receive in production, so point your sandbox endpoint at your integration and test against them. See [Collect Webhooks](/api-reference/tazapay-api/collect-webhook) for the full list of events and their payloads. ## **Create funding for testing Payouts** By simulating a collect transaction, you generate a dummy balance in your test account. This balance can then be used to fund payout requests, enabling you to test the complete payout flow end-to-end - from receiving funds to disbursing them - without using real money. This can be done by navigating to [**Sandbox dashboard**](https://dashboard-sandbox.tazapay.com/)\*\* -> Virtual Accounts/Wallets -> Simulate Collect.\*\* You can simulate to any of the following states of collect - ## Collect State Flows | Fiat | State Flows | Description | | ----------------------- | --------------------------------------------------------------------- | | `on_hold` → `succeeded` | Collect held for review and, upon clearance, settled to the merchant. | | `on_hold` → `failed` | Collect held for review and rejected - compliance failure. | | `succeeded` | Collect settled successfully. | | `failed` | Collect rejected outright. | ## Collect State Flows | Crypto | State Flow | Description | | :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `on_hold` → `detected` → `succeeded` | Collect held for review, cleared, then detected on the blockchain. Once confirmed on-chain, the collect settles successfully. | | `on_hold` → `detected` → `failed` | Collect held for review, cleared, then detected on the blockchain but the on-chain transaction ultimately failed or was rejected post-detection. | | `on_hold` → `succeeded` | Collect held for review and, upon clearance, settled to the merchant. | | `on_hold` → `failed` | Collect held for review and rejected - compliance failure. | | `detected` → `failed` | Crypto transaction detected on the blockchain but never confirmed. | | `detected` → `succeeded` | Crypto transaction detected on the blockchain and successfully confirmed on-chain. Funds settled to merchant. | | `succeeded` | Collect settled successfully. | | `failed` | Collect rejected outright. | # Simulate entity status on Sandbox Source: https://developer.tazapay.com/api-reference/tazapay-api/simulate-entity-status-in-sandbox Entity creation is now available in [sandbox](https://dashboard-sandbox.tazapay.com/) by default. You can create entities and simulate the entity status, enabling you to test entity flows end-to-end in a fully controlled environment. ## **Possible values of entity status** | Entity status | Description | | ------------- | -------------------------------------------------------------------------------------------- | | `pending` | The entity is pending review and requires action from the merchant. | | `approved` | The entity has been approved and is ready to be used for creating on-behalf-of transactions. | | `rejected` | The entity has been rejected and cannot be used to create on-behalf-of transactions. | According to your entity status, you can test you downstream dependednt payout and collect integrations that depend on your entity status. This can be done by navigating to **Sandbox dashboard -> Entities -> Entity Detail Page -> Simulate Entity Review.** # Submit Entity Source: https://developer.tazapay.com/api-reference/tazapay-api/submit-entity-business post /v3/entity/{id}/submit Submits an entity for approval # SWIFT GPI Tracking Source: https://developer.tazapay.com/api-reference/tazapay-api/swift-gpi-tracking ## Overview Tazapay's SWIFT GPI Tracking gives you real-time visibility into the journey of your SWIFT payouts through the initiating and correspondent banking chain. Each transfer is identified by a UETR (Unique End-to-End Transaction Reference) and tracked hop-by-hop until funds reach the beneficiary. Tracking events are delivered as webhook notifications and do not affect the payout lifecycle status (succeeded, failed, etc.). ## Key Concepts | Term | Description | | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | UETR | Unique End-to-End Transaction Reference. A UUID assigned to every SWIFT transfer for end-to-end tracking. | | GPI | Global Payments Innovation — SWIFT's real-time tracking layer for cross-border transfers. | | GPI hop | Each correspondent bank that processes the transfer generates a status update (a "hop"). Tazapay emits a webhook on every hop. | | `payout.gpi_tracking` | The Tazapay webhook event emitted on every new GPI hop. Additive — does not change `payout.status`. | ## Availability * SWIFT GPI Tracking is available for all eligible SWIFT payouts processed by Tazapay. * Tracking is delivered via webhook. GET API access is coming soon. * GPI Tracking is free during the launch period. After the initial rollout window, it will move to an opt-in paid feature — you'll be notified in advance before any change takes effect. ## Webhook Event: `payout.gpi_tracking` ### When is it fired? A `payout.gpi_tracking` event is emitted every time a new status update is received for a SWIFT transfer — typically once per correspondent bank hop. Every event includes the full cumulative timeline, so you always have the complete picture in a single payload. ### Event Schema | Field | Type | Description | | :-------------------------------------- | :------- | :------------------------------------------------------------------------------------------------ | | `type` | string | Always `"payout.gpi_tracking"` | | `id` | string | Event ID (`evt_gpi_...`) | | `created_at` | ISO 8601 | When this event was generated | | `data.id` | string | Payout ID (`pot_...`) | | `data.status` | string | Payout lifecycle status — not modified by GPI events | | `data.tracking_details.tracking_type` | string | Always `"uetr"` | | `data.tracking_details.tracking_number` | UUID | The UETR of the SWIFT transfer | | `data.gpi.latest.reasonCode` | string | Most recent GPI status code (e.g. `ACSP/G000`, `ACSC`, `ACCC`, `RJCT/OTHERS`) | | `data.gpi.latest.statusDescription` | string | Human-readable description of the latest GPI event | | `data.gpi.latest.timestamp` | ISO 8601 | Timestamp of the latest GPI event | | `data.gpi.timeline[]` | array | Full ordered list of all GPI hops. Each entry has: `reasonCode`, `statusDescription`, `timestamp` | ## GPI Status Codes | `reasonCode` | Status | Meaning | `statusDescription` | | :------------ | :---------- | :----------------------------------------------------- | :------------------------------------------------------------------ | | `ACSP/G000` | IN\_TRANSIT | Payment forwarded to next GPI agent | In transit – with intermediary bank | | `ACSP/G001` | IN\_TRANSIT | Forwarded to non-GPI bank; no further updates expected | In transit – sent to non-tracked bank (further updates unavailable) | | `ACSP/G002` | IN\_TRANSIT | Processing with correspondent bank | In transit – processing with correspondent bank | | `ACSP/G003` | IN\_TRANSIT | Processing with correspondent bank | In transit – processing with correspondent bank | | `ACSP/G004` | IN\_TRANSIT | Processing with correspondent bank | In transit – processing with correspondent bank | | `ACSC` | DELIVERED | Funds received by beneficiary bank | Funds received by beneficiary bank | | `ACCC` | CREDITED | Funds credited to beneficiary account | Funds credited to beneficiary account | | `RJCT/OTHERS` | REJECTED | Payment rejected by a bank in the chain | Rejected | ## Sample Payload ```json expandable theme={null} { "type": "payout.gpi_tracking", "id": "evt_gpi_123", "object": "event", "created_at": "2025-11-28T10:12:01Z", "data": { "id": "pot_123", "object": "payout", "type": "swift", "status": "succeeded", "tracking_details": { "tracking_type": "uetr", "tracking_number": "11111111-2222-3333-4444-555555555555" }, "gpi": { "latest": { "reasonCode": "ACCC", "statusDescription": "Funds credited to beneficiary account - AAAABBCC123", "timestamp": "2025-11-28T16:20:00Z" }, "timeline": [ { "reasonCode": "ACCC", "statusDescription": "Funds credited to beneficiary account - AAAABBCC123", "timestamp": "2025-11-28T16:20:00Z" }, { "reasonCode": "ACSC", "statusDescription": "Funds received by beneficiary bank - AAAABBCC123", "timestamp": "2025-11-28T15:38:10Z" }, { "reasonCode": "ACSP/G004", "statusDescription": "In transit – processing with correspondent bank - AAAABBCC123", "timestamp": "2025-11-28T14:00:00Z" }, { "reasonCode": "ACSP/G003", "statusDescription": "In transit – processing with correspondent bank - AAAABBCC123", "timestamp": "2025-11-28T13:00:00Z" }, { "reasonCode": "ACSP/G002", "statusDescription": "In transit – processing with correspondent bank - AAAABBCC123", "timestamp": "2025-11-28T12:00:00Z" }, { "reasonCode": "ACSP/G001", "statusDescription": "In transit – sent to non-tracked bank (further updates unavailable) - AAAABBCC123", "timestamp": "2025-11-28T11:05:00Z" }, { "reasonCode": "ACSP/G000", "statusDescription": "In transit – with intermediary bank - AAAABBCC123", "timestamp": "2025-11-28T10:10:40Z" } ] } } } ``` ## Implementation Notes * GPI tracking does not affect `payout.status`. It is additive event data only. * Every `payout.gpi_tracking` event contains the full cumulative timeline — not a delta. * If the transfer passes through a non-GPI-enabled bank (`ACSP/G001`), no further GPI hops will be reported. The last known status is retained. * `RJCT` events are normalised to `RJCT/OTHERS` for consistency across all banking rails. * Existing SWIFT payouts without a stored UETR will not be retro-tracked. ## GET API — Coming Soon GPI tracking data will also be available inline via the existing payout GET API response. This will allow you to fetch the current GPI status and full timeline on demand, without relying solely on webhooks. Coming soon. You'll be notified as soon as this becomes available. ## Edge Cases | Scenario | Behaviour | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | Tracking service unavailable | Tazapay retries automatically. No event is emitted until the hop is confirmed. You may see a delay between hops during outages. | | Non-GPI bank in chain | Tracking stops at the last GPI-enabled bank. The `ACSP/G001` event will indicate this explicitly. | | No GPI events received | No `payout.gpi_tracking` event is emitted. The payout status remains unchanged. | | UETR not available | GPI tracking will not be available for this transfer. No event will be emitted. | # Update a lightning invoice Source: https://developer.tazapay.com/api-reference/tazapay-api/update-a-lightning-invoice put /v3/lightning_invoice_bolt11/{id} # Update Payin Source: https://developer.tazapay.com/api-reference/tazapay-api/update-a-payin put /v3/payin/{id} Update a payin without confirming You can update a payin only when a payin is in requires\_payment\_method state. # Update Beneficiary Source: https://developer.tazapay.com/api-reference/tazapay-api/update-beneficiary put /v3/beneficiary/{id} This lets you update an existing beneficiary ## **For beneficiaries having successful payouts, the following information cannot be updated** * Type (business or individual) * Beneficiary Name * Account Number / IBAN * Country * Existing Bank Codes (SWIFT, IFSC, BSB\_CODE, ABA\_CODE, etc.). Additional bank codes can be added. **In these scenarios, you can create a new beneficiary with the updated details.** # Expire Checkout Source: https://developer.tazapay.com/api-reference/tazapay-api/update-checkout-copy post /v3/checkout/{id}/expire To expire the checkout # Update Checkout Source: https://developer.tazapay.com/api-reference/tazapay-api/update-checkout-session put /v3/checkout/{id} To update the checkout # Update Collection Account Source: https://developer.tazapay.com/api-reference/tazapay-api/update-collection-account put /v3/collection_account/{id} Update the alias or metadata of an existing collection account, or disable or re-enable it by supplying `action`. In **production**, disabling and re-enabling are asynchronous. The call creates a request against the account and returns immediately — the account keeps its current status until that request reaches `succeeded`. The response carries the account only: it does **not** include a `requests` array, so track progress by subscribing to the [collection account webhooks](/api-reference/tazapay-api/collection-account-webhooks) or by polling the list endpoint. In **sandbox**, disabling and re-enabling are synchronous. No request is created, no lifecycle webhook fires, `reason` is not recorded, and the returned account already reflects the new `status`. To exercise the asynchronous production flow in sandbox, drive the request states with the sandbox simulation endpoint instead. Preconditions for `action`: - `disable` — the account must currently be `enabled`. Wallet accounts cannot be disabled through this endpoint. - `reenable` — the account must currently be `disabled`, must have been disabled by you rather than by Tazapay, and must have `is_reenablement_supported` set to `true`. - Either action is rejected while another request is already in progress against the account. # Update Entity Source: https://developer.tazapay.com/api-reference/tazapay-api/update-entity put /v3/entity/{id} Update an existing entity # Update Payment Attempt Source: https://developer.tazapay.com/api-reference/tazapay-api/update-payment-attempt put /payment_attempt/{id} # Update Refund Source: https://developer.tazapay.com/api-reference/tazapay-api/update-refund put /refund/{id} This endpoint updates an already existing refund object. # Add Document to a Resource Source: https://developer.tazapay.com/api-reference/tazapay-api/upload-document post /v3/document This lets you attach a document to any Tazapay resource like payout, entity etc # Upload Document to Tazapay Source: https://developer.tazapay.com/api-reference/tazapay-api/upload-document-to-tazapay post /v3/metadata/doc/upload This lets you generate a temporary pre-signed URL to upload your document ## Uploading to the Pre-signed URL After calling this endpoint, you will receive a pre-signed URL in the response. Use this URL to upload your document via a **PUT** request. Maximum file size is **50 MB**. ```bash theme={null} curl -X PUT "https://your-presigned-url.s3.amazonaws.com/path?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..." \ -H "Content-Type: application/pdf" \ --upload-file /path/to/document.pdf ``` Set the `Content-Type` header to match your file type (e.g., `application/pdf`, `image/png`, `image/jpeg`). # User Source: https://developer.tazapay.com/api-reference/tazapay-api/user The Tazapay User Object represents the user of the Tazapay platform. It stores user information, enabling businesses to manage user creation and provide a better user experience. ## Object Structure ```json JSON expandable theme={null} { "status": "success", "message": "customer created successfully", "data": { "id": "cus_abc123xyz456", "object": "customer", "created_at": "2025-10-13T14:30:00Z", "name": "Andrew Robin", "email": "andrew.robin@example.com", "country": "US", "phone": { "calling_code": "1", "number": "2025550183" }, "billing_address": [ { "name": "Andrew Robin", "address": { "line1": "123 Main Street", "line2": "Apt 45B", "city": "New York", "state": "NY", "country": "US", "postal_code": "10001" }, "phone": { "calling_code": "1", "number": "2125550199" }, "label":"home" } ], "shipping_address": [ { "name": "Andrew Robin", "address": { "line1": "789 Broadway Avenue", "line2": "Suite 500", "city": "New York", "state": "NY", "country": "US", "postal_code": "10003" }, "phone": { "calling_code": "1", "number": "9175550132" }, "label":"home" } ], "metadata": { "referral_code": "REF2025ABC" } } } ``` ## Parameters ### Customer | Field | Subfield | Type | Description | | :---------------- | :------- | :--------------------- | :------------------------------------------------------------------------ | | id | | string | The unique identifier for the customer. | | object | | string | The type of object, which is "customer". | | created\_at | | string (ISO Timestamp) | The timestamp when the customer object was created. | | name | | string | The name of the customer. | | email | | string | The email address of the customer. | | country | | string | The country of the customer (e.g., SG for Singapore). | | phone | | object | The phone details of the customer. (See Phone Table) | | billing\_address | | object | The billing details of the customer. | | | name | string | The name associated with the billing details. | | | address | object | The address associated with the billing details. (See Address Table) | | | phone | object | The phone details associated with the billing address. (See Phone Table) | | | label | string | Denotes the type of address (Example - home, work) | | shipping\_address | | object | The shipping details of the customer. | | | name | string | The name associated with the shipping details. | | | address | object | The address associated with the shipping details. (See Address Table) | | | phone | object | The phone details associated with the shipping address. (See Phone Table) | | | label | string | Denotes the type of address (Example - home, work) | | metadata | | json | Set of key-value pairs attached to the customer | ### Phone | Field | Type | Description | | :------------ | :----- | :-------------------------------------------------------------- | | calling\_code | string | The international calling code for the customer's phone number. | | number | string | The phone number of the customer. | ### Address | Field | Type | Description | | :----------- | :---------- | :----------------------------------------------- | | line1 | string | The first line of the address. | | line2 | string | The second line of the address | | city | string | The city of the address. | | state | string/null | The state or province of the address (optional). | | country | string | The country code (e.g., SG for Singapore). | | postal\_code | string | The postal code of the address. | # Verification Webhooks Source: https://developer.tazapay.com/api-reference/tazapay-api/verification-webhooks These notify you when a payee verification finishes processing. **Verification status specific events** | Event | Description | Default | | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :------ | | payee\_verification.completed | Triggered when a verification finishes with `verification_status` of `valid` or `invalid` | on | | payee\_verification.failed | Triggered when a verification fails to complete (e.g. provider timeout or error) - no fee is charged for this outcome | on | Both events are enabled by default for every webhook endpoint you configure. A verification that resolves to `not_supported` does not trigger either event, since no verification attempt actually ran. **Sample Events** **payee\_verification.completed** ```json JSON expandable theme={null} { "type": "payee_verification.completed", "id": "evt_d6a633obm14biavhciig", "object": "event", "created_at": "2026-04-07T10:00:05Z", "data": { "id": "pyv_d6a633obm14biavhcia0", "object": "payee_verification", "verification_status": "valid", "status_description": "", "beneficiary": "bnf_d6a633ogm14biavhci0g", "beneficiary_details": { "name": "John Doe", "type": "individual", "destination_details": { "type": "bank", "bank": { "account_number": "9876543210", "account_type": "savings", "bank_codes": { "ifsc_code": "HDFC0001234" }, "bank_name": "HDFC Bank", "country": "IN", "currency": "INR" } } }, "verified_information": { "name_match_details": { "type": "continuous", "value": 0.97, "summary": "strong_match" }, "account_exists": true, "beneficiary_type": "individual" }, "balance_transaction": { "holding_currency": "USD", "balance_impact": -10, "balance_transaction_id": "btr_d6a633obm14biavhci90" }, "created_at": "2026-04-07T10:00:00Z", "updated_at": "2026-04-07T10:00:05Z" } } ``` **payee\_verification.failed** ```json JSON expandable theme={null} { "type": "payee_verification.failed", "id": "evt_d6a633pcn24biavhcj20", "object": "event", "created_at": "2026-04-07T10:00:05Z", "data": { "id": "pyv_d6a633pcn24biavhcj30", "object": "payee_verification", "verification_status": "failed", "status_description": "Verification provider unavailable", "beneficiary": "", "beneficiary_details": { "name": "John Doe", "type": "individual", "destination_details": { "type": "bank", "bank": { "account_number": "9876543210", "country": "IN", "currency": "INR" } } }, "created_at": "2026-04-07T10:00:00Z", "updated_at": "2026-04-07T10:00:00Z" } } ``` # Get Virtual Account Metadata Source: https://developer.tazapay.com/api-reference/tazapay-api/virtual-account-metadata get /v3/metadata/collection_account/virtual_account Returns metadata about the virtual accounts that can be created for a given country, currency, and entity. Use this to discover available payment method types, transfer limits, fund transfer networks, and on_behalf_of support. # Get Wallet Metadata Source: https://developer.tazapay.com/api-reference/tazapay-api/wallet-metadata get /v3/metadata/collection_account/wallet Returns metadata about the stablecoin wallets that can be created for a given entity. Use this to discover available blockchains, limits, compliance requirements, and on_behalf_of support. # Checkout on behalf of Source: https://developer.tazapay.com/cards/checkout-on-behalf-of/checkout-on-behalf-of Learn how platform merchants can create checkout sessions on behalf of their sub-entities using Checkout OBO. Tazapay's **Checkout On Behalf Of (OBO)** capability allows platforms, marketplaces, and financial institutions to collect payments on behalf of their entities: sellers, businesses, or individuals registered under your merchant account. OBO is supported across both Tazapay payment acceptance products: * **Checkout** — a hosted payment link that produces a `checkout` object * **Payin** — whitelabelled payment methods embedded in your own UI that produce a `payin` object In both cases, passing `on_behalf_of` ensures funds are correctly attributed and traceable to the intended recipient. *** ## Use Cases * **Marketplace Platform** — A marketplace creates checkout sessions on behalf of individual sellers, ensuring payments are correctly attributed to each seller's entity. * **Payment Aggregator** — A licensed payment aggregator processes payments on behalf of multiple merchants under a single parent account. * **Bill Payment Platform** — A bill payment aggregator collects payments on behalf of utility companies, telecom providers, or other service entities. * **Digital Wallet Recharge** — A financial institution allows users to recharge prepaid wallets or accounts belonging to third-party entities. *** ## How It Works 1. **Create and submit an entity** — Register the seller, business, or individual under your merchant account and submit them for review. 2. **Wait for approval** — The entity must reach `submitted` status (or `approved`, if mandatory approval is enabled on your account) before it can be used in OBO sessions. 3. **Create a Checkout or Payin** — Pass the approved entity ID in the `on_behalf_of` field. 4. **Customer completes payment** — Tazapay creates a `checkout` or `payin` object attributed to the entity. 5. **Handle webhooks** — Listen for `checkout.paid` or `payin.succeeded` to confirm payment. 6. **Manage settlements / Create Payouts** — Settled funds are received in aggregate to your account. You can either receive them as a bulk settlement to your bank account, or use the balance to fund onward payouts via Tazapay. See Settlement for details. *** ## Step 1: Create an Entity An entity represents the business or individual on whose behalf you're collecting payment — a seller, agent, or service provider registered under your platform's merchant account. Tazapay supports two entity types: * **Business Entity** — for registered companies and legal entities * **Individual Entity** — for sellers, agents, freelancers, or sole proprietors Before an entity can be used in an OBO session, it must be in `approved` status. Think of entities as the sub-accounts sitting under your platform. Every payment you collect on their behalf is fully attributed and traceable back to them. ### Relevant Links 1. [Business Entity Requirements — Full Onboarding](/getting-started/overview/onboarding-requirements) 2. [Individual Entity Requirements — Full Onboarding](/getting-started/overview/onboarding-requirements) 3. [Entity Requirements — Simplified Onboarding](/Global-Money-Movement/connected-accounts/simplified-entity-creation) 4. [Create Entity API](/api-reference/tazapay-api/create-entity) 5. [Submit Entity API](/api-reference/tazapay-api/submit-entity-business) *** ## Step 2: Create a Checkout or Payin Once you have an approved entity, include its ID in the `on_behalf_of` field when creating a Checkout or Payin. This is the only step needed to attribute the payment to the correct entity. ### Request ```json theme={null} POST /v3/checkout { "invoice_currency": "USD", "amount": 100000, "on_behalf_of": "ent_d3inm6ami8u10oqfm", "customer_details": { "name": "Andrea Lark", "country": "SG", "email": "andrea@example.com", "phone": { "calling_code": "65", "number": "87654321" } }, "success_url": "https://mystore.com/success_page", "cancel_url": "https://mystore.com/try_again", "webhook_url": "https://mystore.com/internal/webhook", "transaction_description": "Payment to seller", "reference_id": "mystore_order_00001" } ``` ### Key fields | Field | Type | Required | Description | | :------------- | :----- | :--------- | :------------------------------------------------------------------------------------------------------------------------------ | | `on_behalf_of` | string | Optional\* | ID of the entity on whose behalf the checkout is created. Must be an entity belonging to your merchant account. Format: `ent_*` | \*Required if your account has the **Mandatory OBO information for checkout** configuration enabled. ### Response The response includes the hosted checkout `url` and echoes back `on_behalf_of`: ```json theme={null} { "id": "chk_cirsp2sl4ar024j0akj0", "object": "checkout", "on_behalf_of": "ent_d3inm6ami8u10oqfm", "url": "https://checkout.tazapay.com/transaction=...", "payment_status": "pending", "status": "active", ... } ``` ### Relevant Links * [Create Checkout API](/api-reference/tazapay-api/create-checkout) * [Checkout Object Reference](/api-reference/tazapay-api/checkout) *** ## Step 3: Handle the Resulting Payin When the customer completes payment on the hosted checkout page, Tazapay creates a linked Payin. The Payin **automatically inherits** the `on_behalf_of` value from the checkout session — no additional steps are required. You can retrieve the Payin using the `payin` field in the Checkout response or via the [Get Checkout API](/api-reference/tazapay-api/get-checkout-session). *** ## Step 4: Handle Checkout & Payin Events / Webhooks Tazapay sends webhooks for all checkout and payin status changes. When OBO is used, all webhook payloads include `on_behalf_of` in the `data` object. ### Example: checkout.paid webhook (OBO) ```json theme={null} { "type": "checkout.paid", "created_at": 958793503, "data": { "id": "chk_ahfafooi7ibakbfahoan", "object": "checkout", "payin": "pay_bfiuafuiafianifnao", "payment_status": "paid", "on_behalf_of": "ent_d3inm6ami8u10oqfm", ... }, "id": "evt_auigfianfoangohuehg", "object": "event" } ``` ### Best Practices * Always verify webhook signatures * Rely on webhooks (not polling) for final payment outcomes * Store the `on_behalf_of` value from webhook payloads for reconciliation ### Relevant Links 1. [Checkout Webhook Events](/api-reference/tazapay-api/checkout-webhooks) 2. [Payin Webhook Events](/api-reference/tazapay-api/payin-webhook) 3. [Checkout States](/api-reference/tazapay-api/checkout) 4. [Payin States](/api-reference/tazapay-api/payin) *** ## Account Configurations Two merchant-level configurations control Checkout OBO behaviour. These are set by Tazapay on your account: | Configuration | Description | | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Mandatory OBO information for checkout** | When `enabled`, all checkout creation requests must include `on_behalf_of`. Requests without it will be rejected with `on_behalf_of_required`. | | **Mandatory entity approval for checkout** | When `enabled`, the entity specified in `on_behalf_of` must have `approval_status: approved`. Submitted but unapproved entities will be rejected with `entity_not_approved`. | Contact your Tazapay account manager to enable these configurations. *** ## Error Reference | Error Code | HTTP Status | Message | | :---------------------- | :---------- | :--------------------------------------------------------------------- | | `on_behalf_of_required` | 400 | `on_behalf_of` field is required for this merchant account | | `entity_not_approved` | 400 | The entity must be approved before creating a checkout on their behalf | | `entity_rejected` | 400 | Checkout cannot be created for a rejected entity | | `entity_id_mismatch` | 400 | The entity does not belong to the authenticated merchant account | # List The Payment Methods On Your Own Page Source: https://developer.tazapay.com/cards/integration/list-the-payment-methods-on-your-own-page With Tazapay, you can also choose to control the payment method selection experience for your customers. You can display the payment methods on your application and only redirect to Tazapay after the customer has selected a payment method. # Integration Steps ## Step 1: Set up your Tazapay account Before integrating Tazapay Checkout, ensure you have a Tazapay account. [Sign up](https://dashboard.tazapay.com/) if you haven't already. ## Step 2: Create a Checkout Session The Checkout Session is the core concept in Tazapay Checkout. It contains all the details about the transaction, such as the amount, currency, customer details and the payment methods. Specify the payment method the customer selected in the field `payment_methods`. > **Payment Method Nomenclature** > > Each payment method is represented by a unique string in Tazapay. The name for a payment method is the combination of the payment method name and the currency in which the customer is charged. For example, the name for Paynow in Singapore is `paynow_sgd` > > Related Links: > > 1. List of payment methods supported by Tazapay > 2. [Collection Methods API](/api-reference/tazapay-api/collection-methods-api) - This returns the Tazapay name and other properties of each payment method > 3. Checkout API ### Sample cURL ```Text cURL theme={null} curl --request POST \ --url https://service-sandbox.tazapay.com/v3/checkout \ --header 'accept: application/json' \ --header 'authorization: Basic YWtfdGVzaF9ZTFNVQUUwVjRCSEpIOFg0ODZPQzpza190ZXN0X0hNOEM3SEVSV1BmODVPZnFCMXhLTUJJMWlENnVWYTEyUWN2VE5ZeVJhSHhRZjVTOW9pZUtoOVZzejg3cnhtSEpaSlcyTHdVc0NSY2RWbUR0d0U4Q0VkdWNIUXRnNVQzVjl1NkltQWludkdiMjhWeXhTVVlsTTFMWWllbU80THFt' \ --header 'content-type: application/json' \ --data '{ "customer_details": { "name": "Andrea Lark", "email": "andrea@example.com", "country": "VN" }, "invoice_currency": "USD", "amount": 10000, "transaction_description": "1 x T-shirt", "payment_methods":["bank_push_vnd"] }' ``` ## Step 3: Redirect customers to Tazapay checkout Calling the checkout API in Step 2 provides the following response. Redirect the customer to Tazapay's hosted payment page using the URL. ```Text JSON theme={null} { "status": "success", "message": "", "data": { "amount": 10000, "amount_paid": 0, "billing_details": null, "cancel_url": "", "created_at": "2024-07-19T10:11:07.832914998Z", "customer": "cus_cq8i3c4j2pdpn2r2lah0", "customer_details": { "country": "VN", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "", "number": "" } }, "customer_fee_percentage": 0, "expires_at": null, "holding_currency": "USD", "id": "chk_cqd3nep5ct0u7aakeco0", "invoice_currency": "USD", "items": [], "latest_payment_attempt": "", "metadata": null, "object": "checkout", "paid_in_excess": false, "partially_paid": false, "payin": "chk_cqd3nep5ct0u7aakeco0", "payment_attempts": [], "payment_methods": [ "bank_push_vnd" ], "payment_status": "unpaid", "payment_status_description": "", "reference_id": "", "remove_payment_methods": [], "shipping_details": null, "statement_descriptor": "", "status": "active", "success_url": "", "token": "tGxhgHg5USrT3Gizxu-aL-GFF5FhyaCT4KHyXQXcxZE=", "transaction_data": [], "transaction_description": "1 x T-shirt", "transaction_documents": [], "url": "https://checkout-sandbox.tazapay.com/transaction/tGxhgHg5USrT3Gizxu-aL-GFF5FhyaCT4KHyXQXcxZE=", "webhook_url": "" } } ``` ## Step 4: Handle post-payment events Tazapay sends events to your webhook endpoint to notify you about changes in the Checkout Session status. Set up a webhook endpoint to handle events like checkout.paid. > Related Links: > > 1. List of checkout events > 2. List of payment attempt events > 3. Configuring your webhook endpoint on the Tazapay dashboard # Customisation and Configuration You can configure the appearance and behaviour of the Checkout Page ## Logo You can add your logo to the Checkout Page > Related Guide: Adding logo to the Checkout Page ## Transaction Description You can add a transaction description to display to the customer on the Checkout Page. This is typically the description of the goods / services the merchant is paying for. Pass appropriate values in the `transaction_description` field in the checkout API. # Native / Custom Integration Source: https://developer.tazapay.com/cards/integration/native-custom-integration Tazapay's Payin API allows for a native custom integration, which provides a high degree of flexibility and control over the payment experience. You can tailor the payment process to fit seamlessly into your application. **Advantages:** * **Custom User Experience**: Design the payment flow to match your application's look and feel * **Flexible Payment Methods**: Easily add or modify payment methods as needed * **Enhanced Security**: Implement security measures tailored to your specific requirements * **Detailed Control**: Gain granular control over the payment process, including error handling and status tracking **Lifecycle of a Payin:** 1. **Create a Payin** — Begin by creating a Payin on your server. This specifies the amount, currency, and other details of the payment. 2. **Confirm the Payin** — Confirm the Payin on your server/client-side, potentially requiring customer authentication. 3. **Complete the Payment** — Handle post-payment activities based on the payment outcome. # No Code Options Source: https://developer.tazapay.com/cards/integration/no-code-options For businesses seeking to integrate Tazapay without extensive coding or technical expertise, we offer several no-code options. ## Payment Links * You can create and share customisable payment links with your customers via email, SMS or social media. * You can create these links from [the Tazapay dashboard](https://dashboard.tazapay.com). ## E-commerce Plugins * You can integrate Tazapay with popular e-commerce platforms like Shopify and Woocommerce. * This is perfect for online stores looking to add a secure payment solution without custom development. # Cards Embed Source: https://developer.tazapay.com/cards/integration/payment-embed You can integrate with Tazapay's Payment Embed directly on your checkout page. The Tazapay's Payment Embed simplifies the payment process by combining various payment methods - such as credit and debit cards and local options - into a a single, cohesive interface. This unified approach not only ensures a smooth and consistent user experience but also reduces abandonment, thereby increasing conversion rates. ## Standout Features of the Payment Embed * *Ease of Integration and Maintenance.* The integration process is straightforward with comprehensive documentation. The scalability of the Payment Embed means it can grow with your business, accommodating new payment methods and markets as needed. * *High Degree of Customisability.* You can tailor the look and feel of the payment interface to be seamless with your application. * *Security*. Leveraging Tazapay's security infrastructure, the Payment Embed ensures that all transactions are secure and compliant with global standards such as PCI DSS. > Related Guide: Integrating Tazapay's Payment Embed # The Hosted Page Lists The Payment Methods Source: https://developer.tazapay.com/cards/integration/the-hosted-page-lists-the-payment-methods # Overview Tazapay Checkout is a prebuilt, hosted payment page optimized for conversion. It allows merchants to redirect customers to a Tazapay-hosted page where they can select a payment method and complete their purchase. This guide provides an overview of how to integrate Tazapay Checkout, covering setup, customization, and usage. # Integration Steps ## Step 1: Set up your Tazapay account Before integrating Tazapay Checkout, ensure you have a Tazapay account. [Sign up](https://dashboard.tazapay.com/) if you haven't already. ## Step 2: Create a Checkout Session The Checkout Session is the core concept in Tazapay Checkout. It contains all the details about the transaction, such as the amount, currency, customer details and the payment methods. > Related Link: Checkout API ### Sample cURL ```Text cURL theme={null} curl --request POST \ --url https://service-sandbox.tazapay.com/v3/checkout \ --header 'accept: application/json' \ --header 'authorization: Basic YWtfdGVzaF9ZTFNVQUUwVjRCSEpIOFg0ODZPQzpza190ZXN0X0hNOEM3SEVSV1BmODVPZnFCMXhLTUJJMWlENnVWYTEyUWN2VE5ZeVJhSHhRZjVTOW9pZUtoOVZzejg3cnhtSEpaSlcyTHdVc0NSY2RWbUR0d0U4Q0VkdWNIUXRnNVQzVjl1NkltQWludkdiMjhWeXhTVVlsTTFMWWllbU80THFt' \ --header 'content-type: application/json' \ --data '{ "customer_details": { "name": "Andrea Lark", "email": "andrea@example.com", "country": "VN" }, "invoice_currency": "USD", "amount": 10000, "transaction_description": "1 x T-shirt", "payment_methods":["bank_push_vnd"] }' ``` ## Step 3: Redirect customers to Tazapay checkout Calling the checkout API in Step 2 provides the following response. Redirect the customer to Tazapay's hosted payment page using the URL. ```Text JSON theme={null} { "status": "success", "message": "", "data": { "amount": 10000, "amount_paid": 0, "billing_details": null, "cancel_url": "", "created_at": "2024-07-19T10:11:07.832914998Z", "customer": "cus_cq8i3c4j2pdpn2r2lah0", "customer_details": { "country": "VN", "email": "andrea@example.com", "name": "Andrea Lark", "phone": { "calling_code": "", "number": "" } }, "customer_fee_percentage": 0, "expires_at": null, "holding_currency": "USD", "id": "chk_cqd3nep5ct0u7aakeco0", "invoice_currency": "USD", "items": [], "latest_payment_attempt": "", "metadata": null, "object": "checkout", "paid_in_excess": false, "partially_paid": false, "payin": "chk_cqd3nep5ct0u7aakeco0", "payment_attempts": [], "payment_methods": [ "bank_push_vnd" ], "payment_status": "unpaid", "payment_status_description": "", "reference_id": "", "remove_payment_methods": [], "shipping_details": null, "statement_descriptor": "", "status": "active", "success_url": "", "token": "tGxhgHg5USrT3Gizxu-aL-GFF5FhyaCT4KHyXQXcxZE=", "transaction_data": [], "transaction_description": "1 x T-shirt", "transaction_documents": [], "url": "https://checkout-sandbox.tazapay.com/transaction/tGxhgHg5USrT3Gizxu-aL-GFF5FhyaCT4KHyXQXcxZE=", "webhook_url": "" } } ``` ## Step 4: Handle post-payment events Tazapay sends events to your webhook endpoint to notify you about changes in the Checkout Session status. Set up a webhook endpoint to handle events like checkout.paid. > Related Links: > > 1. List of checkout events > 2. List of payment attempt events > 3. Configuring your webhook endpoint on the Tazapay dashboard # Customisation and Configuration You can configure the appearance and behaviour of the Checkout Page ## Logo You can add your logo to the Checkout Page > Related Guide: Adding logo to the Checkout Page ## Transaction Description You can add a transaction description to display to the customer on the Checkout Page. This is typically the description of the goods / services the merchant is paying for. Pass appropriate values in the `transaction_description` field in the checkout API. ## Payment Methods The `payment_methods` field in the checkout API allows you to specify payment methods that you would want for a particular checkout session. The payment methods added to the field would be only surfaced on the hosted payment page. Additionally, you can also remove payment methods for a particular transaction using the `remove_payment_methods` field. > **Payment Method Nomenclature** > > Each payment method is represented by a unique string in Tazapay. The name for a payment method is the combination of the payment method name and the currency in which the customer is charged. For example, the name for Paynow in Singapore is `paynow_sgd` > > Related Links: > > 1. List of payment methods supported by Tazapay > 2. [Collection Methods API](/api-reference/tazapay-api/collection-methods-api) - This returns the Tazapay name and other properties of each payment method # Cards Source: https://developer.tazapay.com/cards/overview/cards Accept credit and debit card payments globally with 3DS authentication Cards Accept payments from major card networks including Visa and Mastercard. ## Card Types Supported * **Credit Cards**: Revolving credit line with delayed settlement * **Debit Cards**: Direct debit from linked bank account * **Prepaid Cards**: Pre-loaded balance with no bank account linkage ## Payment Flow ```mermaid theme={null} sequenceDiagram Customer->>Merchant: Provides card details Merchant->>Tazapay: Authorization request Tazapay->>Card Network: Routes to Visa/Mastercard Card Network->>Issuing Bank: Validates funds/credit Issuing Bank->>Card Network: Approval/Decline Card Network->>Tazapay: Response Tazapay->>Merchant: Authorization result ``` ## Authentication Methods ### Standard (Non-3DS) * Card number, CVV, expiry date * Faster checkout but higher risk * Recommended for low-value transactions ### 3D Secure (3DS) * Additional authentication layer (OTP, biometric, PIN) * **Frictionless flow**: Risk-based authentication, no user action required * **Challenge flow**: User prompted for additional verification * Required for Strong Customer Authentication (SCA) in many regions * Reduces fraud and shifts liability to issuer ## Key Integration Points * **PCI Compliance**: Use Tazapay's hosted payment page or tokenization to avoid PCI scope * **Card Networks**: Visa, Mastercard. * **Global Acceptance**: Works in 150+ countries ## Technical Considerations ### For Developers * Support both 3DS and non-3DS flows based on merchant preference * Handle authorization vs capture flows for pre-authorization scenarios * Implement proper error handling for declined transactions * Use idempotency keys to prevent duplicate charges ## Settlement ### Flexible Settlement Timelines Settlement timelines are customized based on your business needs and transaction volumes: * **Same-day settlement**: Available for high-volume merchants * **Daily settlement**: Standard option for most businesses * **Weekly settlement**: Common for smaller transaction volumes * Settlement frequency can be adjusted as your business scales Settlement timelines are configured during onboarding and can be modified based on changing business requirements. Contact your Tazapay account manager to discuss settlement options. ## Use Cases * **E-commerce**: Online purchases with saved cards * **Subscriptions**: Recurring billing with card on file * **High-value transactions**: 3DS required for enhanced security * **Cross-border payments**: Accept international cards with currency conversion # Choosing How To Collect Payments Source: https://developer.tazapay.com/cards/overview/choosing-how-to-collect-payments Tazapay offers flexible integration options to cater to your business needs and technical capabilities. You can either redirect to a `Tazapay Hosted Page` or build a `Custom Native Integration`. Tazapay also provides various [no-code](/cards/integration/no-code-options) payment options to help you get started quickly. ## Choosing the right integration option | | Redirect to a Tazapay hosted page \| List payment methods on your page | Redirect to a Tazapay hosted page \| Tazapay lists the payment methods | Build a custom native integration | | :------------------------------------- | :---------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | *Experience* | The customer is redirected to Tazapay after they have selected the payment method on your application | The customer is redirected to Tazapay where they choose a payment method | The customer completes the entire payment on your application. | | *Effort to integrate* | Low | Very low | Medium | | *Payment Success Rates* | High | High | Very High | | *API to Integrate* | /v3/checkout | /v3/checkout | /v3/payin | | *What is sent as part of API response* | A redirection URL pointing to a Tazapay hosted page | A redirection URL pointing to a Tazapay hosted page | Information corresponding to the payment method. You can choose how best to display this information to the customer | | *Effort to Maintain* | Low | Very low | Medium | | *Integration Guide* | [Click here](/local-payments/integration/list-the-payment-methods-on-your-own-page) | [Click here](/local-payments/integration/the-hosted-page-lists-the-payment-methods) | [Click here](/local-payments/integration/native-custom-integration) | > 👍 Javascript SDK > > You can also integrate with Tazapay's Javascript SDK to directly embed the payment iFrame on your website for all the payment methods as well as cards. # How Checkout Works Source: https://developer.tazapay.com/cards/overview/how-checkout-works Add a low-code cross-border payment page to your website, online shop or marketplace. Create a session on your server, redirect your customer to a Tazapay-hosted payment page, and receive the result via webhook. The same API, the same objects, the same lifecycle regardless of whether the customer pays with a card or a QR code. ## The Object Hierarchy Every payment flow creates three objects in sequence: | Object | What it represents | Created by | | ------------------- | ----------------------------------------------------------------- | ------------------------ | | **Checkout** | The payment session — amount, currency, customer, allowed methods | You (POST /v3/checkout) | | **Payin** | The collection intent — tracks the full payment lifecycle | Tazapay, automatically | | **Payment Attempt** | A single attempt to pay — one per method try | Tazapay, on each attempt | If a card is declined and the customer retries with a different card, a new Payment Attempt is created on the same Payin. ## The Lifecycle 1. Your server calls `POST /v3/checkout` — returns a hosted payment page `url` 2. You redirect the customer to that `url` 3. Customer selects a payment method, completes authentication 4. Tazapay redirects customer back to your `success_url` or `cancel_url` 5. Tazapay sends webhooks — key events: * `checkout.paid` — payment\_status changes to paid * `payment_attempt.created` — new payment attempt created * `payment_attempt.succeeded` — attempt succeeds * `payment_attempt.failed` — attempt fails * `payment_attempt.processing` — attempt moves to processing * `checkout.expired` — session expires before payment * `checkout.created` — session created ## Checkout Status Fields The Checkout object has two independent status fields that update separately: **`status`** — the session state: * `active` — session is open and the customer can still pay * `expired` — session window closed before payment was completed **`payment_status`** — the payment outcome: * `unpaid` — no payment received yet * `processing` — customer completed all actions but Tazapay hasn't confirmed funds yet; common for async methods like local bank transfer or wire transfer where intermediary banks take time to process * `paid` — payment confirmed ## Creating a Checkout Session ```json theme={null} POST /v3/checkout { "invoice_currency": "USD", "amount": 10000, "customer_details": { "name": "Andrea Lark", "email": "andrea@example.com", "country": "VN" }, "transaction_description": "1 x T-shirt", "payment_methods": ["bank_push_vnd"], "success_url": "https://mystore.com/success", "cancel_url": "https://mystore.com/cancel", "webhook_url": "https://mystore.com/webhooks/tazapay", "reference_id": "mystore_order_00001" } ``` **Sample response:** ```json theme={null} { "status": "success", "data": { "id": "chk_cqd3nep5ct0u7aakeco0", "object": "checkout", "invoice_currency": "USD", "amount": 10000, "amount_paid": 0, "status": "active", "payment_status": "unpaid", "payment_methods": ["bank_push_vnd"], "url": "https://checkout-sandbox.tazapay.com/transaction/tGxhgHg5USrT3Gizxu-aL-GFF5FhyaCT4KHyXQXcxZE=" } } ``` Redirect the customer to the `url` in the response. # Introduction To Checkout Source: https://developer.tazapay.com/cards/overview/introduction-to-checkout Tazapay Checkout is a low-code payment integration for your website/marketplace that creates a Tazapay-hosted payment page so that you can quickly collect cross-border payments on mobile and desktop devices. The customers can also pay in their local currencies using a variety of payment methods and you can get settled in the currency of your choice. You can collect from and disburse to 170+ countries with one low-code integration. Check out Tazapay's list of supported countries and payment methods. #### Here's how the payment page looks like on a desktop: # Managing Payment Methods Source: https://developer.tazapay.com/cards/overview/managing-payment-methods Choose which payment methods need to be displayed to your customers. ## Overview Tazapay supports a variety of payment methods for a particular combination of buyer-seller corridor, invoice currency and transaction amount. You can use an interactive widget on the homepage to simulate a trade and find out the available payment methods. Alternatively, you can also use the collect metadata endpoint. The 'payment\_methods' field in the checkout session endpoint allows you to specify payment methods that you would want for a particular checkout session. The payment methods added to the field would be only surfaced on the hosted payment page. For example, if you only want Wire Transfer and Local Bank Transfer as payment methods in the checkout session, make sure to pass the following field and parameter in the Checkout request body\ `"payment_methods": ["wire_transfer", "local_bank_transfer_sgd"]` > `local_bank_transfer_sgd` is Local Bank Transfer for Singapore. Similarly, Local Bank Transfer for EU countries is `local_bank_transfer_eur` and so on. If the "payment\_methods" field has some undesired values; ex: \["abc", "xyz"], it will throw an error. You can also remove payment methods for a particular transaction using the 'remove\_payment\_methods' field. If you do not want Wire Transfer and Local Bank Transfer as payment methods in the checkout session, make sure to pass the following field and parameter in the Checkout request body\ `"filter": ["wire_transfer", "local_bank_transfer_sgd"]` In case both the fields are present in the request body, the 'payment\_methods' field will take precedence. ## Example: The payment methods available for a buyer from Netherlands are the following for an invoice of USD 500. * Bank Initiation (Internet Banking) aka `bank_initaition_eur` * Card aka `card` * Local Bank Transfer aka `local_bank_transfer_eur` * Wire Transfer aka `wire_transfer` If you only want to have Card and Internet Banking as payment methods for the transaction, you can go either of the two ways below: ### Specifying Payment Methods using 'payment\_methods' field This is the part of the payload for POST /v3/checkout API ```Text JSON theme={null} "payment_methods": ["card","bank_initiation_eur"] ``` ### Filtering out Payment Methods using 'remove\_payment\_methods' field This is the part of the payload for POST /v3/checkout API. ```Text JSON theme={null} "remove_payment_methods": ["local_bank_transfer_eur", "wire_transfer"] ``` Tazapay constantly upgrades its payment collection capabilities by adding new payment methods. It is recommended to use the 'remove\_payment\_methods' instead of 'payment\_methods' field in case you do not want any particular payment method (for example, you may choose to remove asynchronous payment methods like Wire Transfer). Your customers and buyers can access these new payment methods without you having to make any change to your integration. # Reconciliation Source: https://developer.tazapay.com/cards/post-payment/reconciliation All transactions made on Tazapay will appear on your [live dashboard](https://dashboard.tazapay.com) To reconcile and see detailed breakdowns of your payments, please read our FAQ on how to [export CSV reports](https://support.tazapay.com/how-do-i-export-csv-for-payment-reconciliation) and [what the CSV columns mean](https://support.tazapay.com/what-do-the-columns-in-the-exported-csv-file-mean). # Refunds Source: https://developer.tazapay.com/cards/post-payment/refunds You can make refunds to your customers against a particular transaction using the refund endpoint. You can either make a full refund or a partial refund of the initial transaction. You can also make multiple requests for partial refunds provided the sum of these partial refunds does not exceed the transaction amount. Refunds use your funds available with Tazapay. If you do not have sufficient funds with Tazapay, the refund request gets rejected. It is necessary to ensure that you have sufficient funds with Tazapay to process refunds. # Settlements Source: https://developer.tazapay.com/cards/post-payment/settlements Receive funds from Tazapay in your bank account Tazapay makes settlements to your bank account. By default, new users signing up for Tazapay will receive their settlement in a weekly cycle. The day in which you receive your settlement would depend on when you sign up for your Tazapay account. For eg: signing up on a Tuesday would mean you will receive your weekly settlement on Tuesdays. However, you write to us at [support@tazapay.com](mailto:support@tazapay.com) to receive payouts on the day of your choosing. In some cases, you might receive an email asking you to upload documents. This is Tazapay taking necessary risk mitigation measures to keep the network safe. You can reply to the email with the documents or upload it from the dashboard. **Bank account setup:** * Add your bank details by logging in to the Tazapay Dashboard * Tazapay supports local currency bank accounts as well as USD bank accounts * USD settlements come at an additional cost * Your legal business name must match the bank account name # Webhook Events Source: https://developer.tazapay.com/cards/post-payment/webhook-events Use webhooks to get notified of offline/asynchronous events. A webhook is an HTTP endpoint on your server that receives information from Tazapay. Webhooks allow you to get notified of any updates that happen for a transaction outside the payment flow. For example, if a customer successfully completes the payment on the hosted payment page, webhooks instantly notify you of the receiving of funds. Upon receiving the information from Tazapay, you can accordingly proceed for order fulfilment. Currently, Tazapay supports webhooks for any updates related to: 1. The state of the checkout session. 2. The payment attempts for a checkout session. 3. Refund Status. Webhooks are also very useful when a customer chooses an asynchronous mode of payment like Local Bank Transfer. Rather than deploying your resources to constantly poll the Status API, Tazapay will itself send a webhook as soon as the funds are received. Tazapay recommends use of dashboard and GET APIs only for an one-off transaction. For a faster and more-scalable approach, use webhooks. # Test Cards Source: https://developer.tazapay.com/cards/testing/simulating-payments-test-cards Test card details for simulating card payments in sandbox mode Please find the test card details that you can use to complete test transactions in Tazapay. ## Test Card Numbers | Category | Scenarios | Card No. | CVV | Expiry | Password/PIN (Case sensitive) | | :-------------------------- | :----------------------------------------- | :--------------- | :--------------------- | :-------------- | :---------------------------- | | **Without 3DS** | Transaction Success | 4556218578001529 | Any 3 numerical digits | Any future date | \* | | **Without 3DS** | Transaction Declined | 4804262554494753 | Any 3 numerical digits | Any future date | \* | | **With 3DS - Frictionless** | Authentication Successful | 4532691318874448 | Any 3 numerical digits | Any future date | \* | | **With 3DS - Frictionless** | Authentication Failure | 4929653796729263 | Any 3 numerical digits | Any future date | \* | | **With 3DS - Frictionless** | Authorization Successful | 4716858016270272 | Any 3 numerical digits | Any future date | \* | | **With 3DS - Frictionless** | Authorization failure - Insufficient funds | 4556225847192831 | Any 3 numerical digits | Any future date | \* | | **With 3DS - Challenge** | Authentication Successful | 4716959793397708 | Any 3 numerical digits | Any future date | 101010! | | **With 3DS - Challenge** | Authentication Failure | 4716959793397708 | Any 3 numerical digits | Any future date | Any wrong pin | | **With 3DS - Challenge** | Authorization Successful | 4916243871650546 | Any 3 numerical digits | Any future date | \* | | **With 3DS - Challenge** | Authorization failure - Insufficient funds | 4024007127258902 | Any 3 numerical digits | Any future date | \* | ## Usage Notes * **CVV**: You can use any 3 numerical digits * **Expiry Date**: Any future date is accepted * **Password/PIN**: * `*` means no password/PIN required * For challenge flow with authentication successful, use exactly `101010!` (case-sensitive) * For authentication failure, use any incorrect PIN ## Testing Scenarios ### Without 3DS Authentication Use these cards when testing payments that don't require additional authentication: * **Success**: Use `4556218578001529` to simulate a successful payment * **Decline**: Use `4804262554494753` to simulate a declined payment ### With 3DS - Frictionless Flow These cards trigger 3D Secure authentication but complete without user interaction: * Test various authentication and authorization outcomes * No password/PIN required (marked with `*`) ### With 3DS - Challenge Flow These cards require user input during authentication: * Use `101010!` as the password for successful authentication * Use any incorrect PIN to test authentication failure scenarios # Added Support For Passing Beneficiarys Nationality Source: https://developer.tazapay.com/changelog/2025/added-support-for-passing-beneficiarys-nationality ## Applicability **When:** Creating or updating beneficiary objects. ## Field Added * **nationality** (string; ISO 3166-1 alpha-2 country code) ### Description * Optional field * Helps reduce sanction screening false positives * Accepts 2-letter country codes (e.g., `US`, `GB`, `IN`, `FR`, `SG`) ## Changes ### Beneficiary Management Endpoints Beneficiary endpoints now accept and return the `nationality` field. Updated request/response schemas for: * `POST /v3/beneficiary` * `GET /v3/beneficiary/{id}` * `PUT /v3/beneficiary/{id}` **Responses now include `nationality` in the beneficiary object.** ### Payout Endpoints Payout endpoints now include `nationality` inside `beneficiary_details`. Updated response schemas for: * `POST /v3/payout` (when creating with inline beneficiary) * `GET /v3/payout/{id}` * `PUT /v3/payout/{id}` **Payout `beneficiary_details` now includes:** * `beneficiary_details.date_of_birth` * `beneficiary_details.nationality` ## Validation Rules * `nationality` must be a valid 2-letter **ISO 3166-1 alpha-2** country code\ (e.g., `US`, `GB`, `IN`, `FR`) * Field is **optional** — not required for beneficiary creation or payout processing * System automatically normalizes the value to **uppercase** * A validation error is returned if an invalid country code is provided # Bulgaria Currency Transition BGN EUR Source: https://developer.tazapay.com/changelog/2025/bulgaria-currency-transition-bgn--eur ## Change Type **Currency validation / acceptance** ## Region Impacted **Bulgaria-related flows** ## Effective Date **25 December 2025** ## Summary To align with ISO 4217 updates and upstream FX/provider support, Tazapay will discontinue support for **BGN** and require **EUR** as the sole supported currency for Bulgaria-related transactions starting **25 December 2025**. ## What's Changing ### 1. Currency Acceptance for New Transactions From **25 December 2025** onward, any new Bulgaria-related transaction using **BGN** will be rejected. **EUR** will become the only accepted local currency for Bulgaria-related flows across: * Collections * Holding * Checkout * Payment links * Pay-ins * Payouts * Settlements * Refunds * Adjustments ### 2. Historical Visibility * Existing **BGN** transactions will remain visible in the dashboard and reports for historical reference. ## Developer Migration Guidance ### Required Action (for API Integrators) * Update integration logic to ensure **EUR** is used for all Bulgaria-related transactions. * If currency is passed via API parameters, ensure **BGN** is no longer used when the transaction is Bulgaria-linked. ### No Action Required * Transactions already processed in **BGN** require no changes and will remain available for historical viewing and reporting. ## Backward Compatibility Notes * This change affects **only new transaction creation** (and other “new action” flows) after the effective date. * Reporting and dashboard access for historical **BGN** records remains unchanged. # Introduction of Payout Reversal Source: https://developer.tazapay.com/changelog/2025/introduction-of-payout-reversal # Get Payout API Changes The **Get Payout API** has been enhanced to provide additional details for payout reversal scenarios. A new payout state, **`reversed`**, has been introduced along with additional fields to improve traceability and visibility into reversal-related transactions and FX movements. ## New State Introduced * **`reversed`** Indicates that a previously succeeded payout has been successfully reversed. ## New Fields Added * **`reversal_balance_transaction`**\ References the balance transaction created as part of the payout reversal. * **`reversal_payout_fx_transaction`**\ Represents the FX transaction applied during the payout-side reversal process. # Fetch Balance Transaction API Updates have been made to the fee representation for reversal transactions in the **Balance Transaction** object. ## Fee Structure Update For reversal transactions, the API now returns **`third_party_fee`** instead of **`payout_fee`** in the **Fee** object. | Field | Behaviour | Purpose | | ------------ | ----------------- | ----------------------------------------------------------------- | | fee\_details | third\_party\_fee | Distinguishes third-party charges applied during payout reversals | ## FX Structure Update For reversal transactions, the API now returns **`third_party_fx`** along with holding FX transactions in the **FX** object. | Field | Behaviour | Purpose | | --------------- | --------------------- | ----------------------------------------------------------------------- | | fx\_conversions | third\_party\_fx | Represents FX charges applied by third-party providers during reversals | | fx\_conversions | reversal\_holding\_fx | Represents the FX movement on the holding-currency side of a reversal | These updates provide clearer visibility into the fee components associated with reversed payouts. # New Reversal Reason Codes Comprehensive [reason codes](/api-reference/appendix/payout-reversal-reasons) have been introduced for payout reversals to help identify the exact cause of a reversal. ## Relevant Links * [**GET Payout**](/api-reference/tazapay-api/fetch-payout) * [**Payout Webhooks**](/api-reference/tazapay-api/payout-webhooks) * [**GET Balance Transaction**](/api-reference/tazapay-api/fetch-balance-transaction) # New Accept Payments Via We Chat Pay In Thailand Source: https://developer.tazapay.com/changelog/2025/new-accept-payments-via-wechat-pay-in-thailand We are excited to announce a new addition to our payment collection methods. Merchants can now accept payments in Thai Baht (THB) from their customers in Thailand via WeChat Pay. This integration allows you to tap into a massive customer base in Thailand by offering one of the region's most popular and trusted payment methods, directly through the Tazapay platform. For a step-by-step guide on how to configure and use this new payment method, please see our comprehensive documentation. [Read the full guide here](/local-payments/payment-methods/wechat_thb_pay#/) # New Payout Purpose Codes For Payouts Source: https://developer.tazapay.com/changelog/2025/new-payout-purpose-codes-for-payouts To enhance the accuracy and classification of your transactions, we have added two new purpose codes to our Payouts API. These codes are now available for use when creating a payout. The new codes are: 1. **PYR033**: Merchant Settlement 2. **PYR034**: Repatriation Fund Settlement **Resource**: [Payout Purpose](/payouts/payout-network/purpose) # New Support For Major Cryptocurrencies And Stablecoins Source: https://developer.tazapay.com/changelog/2025/new-support-for-major-cryptocurrencies-and-stablecoins We are excited to announce that Tazapay now supports decimal currencies for major cryptocurrencies and popular stablecoins. This allows you to process transactions with greater precision for these digital assets. The newly supported decimal currencies are: * BTC (Bitcoin) * ETH (Ethereum) * USDT (Tether) * USDC (USD Coin) For complete details on how to handle these currencies in your integration, please see our guide [here](/api-reference/appendix/decimal-currencies#/) # Payout Metadata API Field Standardization Source: https://developer.tazapay.com/changelog/2025/payout-metadata-api-field-standardization We have released an update to the Payout Bank Metadata API (`/v3/metadata/payout/bank`) to standardize field names and introduce a more structured format for addresses. This update includes **breaking changes** that will require action on your part. These changes will improve data consistency, reduce errors, and allow for more robust validation. ### **Breaking Changes** To continue using the Payout API without interruption, you **must update your integration** to adopt the following new field names and structures. | Old Field / Structure | New Field / Structure | Description | | ------------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` (as a single string) | `address` (as a structured object) | The address is no longer a single string. It is now a structured object with fields like `address.line1`, `address.city`, `address.state`, and `address.postal_code`. | | `postcode` | `postal_code` | The field for the postal code has been renamed for consistency. | | `phone.contact_code` | `phone.calling_code` | The field for the phone country code has been renamed. | | `phone.contact_number` | `phone.number` | The field for the local phone number has been renamed. | ### **Enhancement** We've also introduced an enhancement to help you prepare for future improvements. * **New `recommended_fields` Object:** The API response now includes a `recommended_fields` object. This will list optional fields that are not part of the primary requirement. * **Important Note:** We have introduced `recommended_fields` to accommodate our expanding network of payment providers. **The number of providers available for routing depends on the number of fields specified from the recommended\_fields parameter for a given beneficiary** ### **Action Required** * You must update your integration to parse the new, structured `address` object and use the updated field names (`postal_code`, `calling_code`, `number`). ## Updated Response Structure: ```json theme={null} { "status": "success", "message": "", "data": { "payout_methods": [ { "beneficiary_type": [ "individual", "business" ], "country": "IN", "currency": "INR", "custom_remitter_support": true, "payout_type": "local", "required_bank_codes": [ "ifsc_code" ], "required_bank_fields": [ "account_holder_name", "bank_name", ], "required_beneficiary_fields": [ "address.line1", "address.city", "address.state", "address.postal_code", "phone.calling_code", "phone.number", "tax_id" ], "supported_destinations": [], "transfer_limit": { "currency": "INR", "maximum": 100000000, "minimum": 128 }, "recommended_fields": { "recommended_bank_fields": [ "account_number" ], "recommended_beneficiary_fields": [ "address.line_1", ], "recommended_bank_codes": [ "ifsc_code" ] } } ] } } ``` # Purpose Codes Update For INR Payouts Source: https://developer.tazapay.com/changelog/2025/purpose-codes-update-for-inr-payouts ## Purpose Codes Documentation Update * Added comprehensive documentation explaining FIRA generation and Purpose Code usage for India payouts. * Includes detailed overview of RBI compliance requirements, purpose code mappings, and best practices for code selection. * Added key compliance notes and warnings about irreversible FIRA generation and potential consequences of incorrect code selection. * New section on best practices for using purpose codes with specific guidelines for different transaction types. Resource: \[/Global-Money-Movement/payouts/local-guides/India (INR)/firc#/]\(/Global-Money-Movement/payouts/local-guides/India (INR)/firc#/) # Revampment Of Wallet Payout And Beneficiary Flows Source: https://developer.tazapay.com/changelog/2025/revampment-of-wallet-payout-and-beneficiary-flows ### **🔐 Travel Rule Compliant Wallet Payouts** We’ve redesigned the wallet payout experience to ensure compliance with global Travel Rule regulations for all outgoing crypto transactions. This revamp introduces new data fields, a state-based approval process and enhanced wallet verification ensuring that all crypto payouts are both secure and regulatorily compliant while maintaining transparency for your business and its beneficiaries. ### **🧩 Enhanced Beneficiary Object** New fields have been added to the beneficiary and destination\_details.wallet objects. These updates ensure accurate capture of required Travel Rule data when creating wallet payouts—whether through the API or dashboard. → [View updated Beneficiary Object](/api-reference/tazapay-api/beneficiary#/) → [See Create Beneficiary API reference](/api-reference/tazapay-api/create-beneficiary#/) ### 🧾 **Wallet Beneficiary State Management & Approvals** Wallet beneficiaries now follow a state-based lifecycle with internal compliance approval for 1st-party wallets before payouts can be initiated. You’ll receive email and webhook notifications for every wallet beneficiary creation and state transition. → [View Beneficiary Webhooks](/api-reference/tazapay-api/beneficiary-webhooks#/) ### **🧠 Wallet Verification (Hosted vs. Self-Hosted)** When adding a wallet beneficiary, you’ll now specify whether the wallet is: * Hosted (on an exchange) * Unhosted (self hosted wallets where you have control over private keys) Depending on the wallet type: * Hosted wallets require wallet screen recordings for verification. * Self-hosted wallets require performing a cryptographic signature, which proves ownership of the wallet address by digitally signing a verification message with the private key. This step can currently be performed only via the Tazapay dashboard. Until verification is complete, the wallet beneficiary will remain in the requires\_action state and payouts will be restricted. All of these wallet beneficiaries can be viewed under Dashboard → Action Required → Wallet Beneficiaries tab ### **👥 Role-Based Access Control (RBAC)** A new permission, “Allow Cryptographic Signature”, has been added under Settings → Manage Team → Payout. This permission controls who can perform cryptographic signatures. All existing users have this enabled by default, but admins can restrict access as needed. # Support For Individual Fields In The Entity Object Source: https://developer.tazapay.com/changelog/2025/support-for-individual-fields-in-the-entity-object * **New `individual` object on entities** * Applicable when `type: "individual"`. * Fields added under `individual`: * `national_identification_number` (object) * `type` (string; supported values: `passport`, `driving_license`, `national_id_card`, `tax_id_number`, `residence_permit`, `other`) * `number` (string) * `date_of_birth` (string; ISO 8601 date format `YYYY-MM-DD`) * `nationality` (string; ISO 3166-1 alpha-2 country code) * **Webhook payload expansion** * Entity webhooks now include `individual` object in `data` when `type: "individual"`. * Events affected: * `entity.created` * `entity.updated` * `entity.submitted` * `entity.approved` ### Changed * **Entity Management endpoints accept and return `individual` fields** * Updated request/response schemas for: * `POST /v3/entity` * `GET /v3/entity/{id}` * `PUT /v3/entity/{id}` * `POST /v3/entity/{id}/submit` * Responses include `individual` object when `type: "individual"`. * **Entity submission requirements for individual entities** * On full entity submission (`POST /v3/entity/{id}/submit`), the following are required for `type: "individual"`: * `individual.national_identification_number.type` * `individual.national_identification_number.number` * `individual.date_of_birth` * `individual.nationality` * For simplified entity creation/update, these fields remain optional. ### Validation Rules * `individual.date_of_birth` must match `YYYY-MM-DD`. * `individual.nationality` must be a 2-letter ISO country code. * `individual.national_identification_number.type` and `.number` must be provided together. ### Compatibility * No breaking changes; additions are backward-compatible and ignorable by existing clients. ### Relevant Links 1. [Create Entity](/api-reference/tazapay-api/create-entity) # Additional information field added to fund transfer networks object Source: https://developer.tazapay.com/changelog/2026/additional-information-field-added-to-fund-transfer-networks-object The Payout Bank Metadata API now returns an `additional_information` field within the `fund_transfer_networks` object, providing supplementary details stored in our system for each network. ## Payout Bank Metadata API ### New Field A new field has been added to the `fund_transfer_networks` array: * **`additional_information`** (string) * Provides any additional information against the fund transfer network ## Backward Compatibility * All fields are optional * No breaking changes to existing integrations ## Relevant Links 1. [Payout Bank Metadata API](/api-reference/tazapay-api/payout-bank) # Beneficiary Name Field Character Limit Source: https://developer.tazapay.com/changelog/2026/beneficiary-name-field-character-limit The beneficiary `name` field now has a maximum character limit of 140 characters. ## Affected Endpoints * **Create Beneficiary** (`POST /v3/beneficiary`) * **Update Beneficiary** (`PUT /v3/beneficiary/{id}`) * **Create Payout** (`POST /v3/payout`) - applies to `beneficiary_details.name` ## Relevant Links 1. [Beneficiary API Documentation](/api-reference/tazapay-api/beneficiary) 2. [Create Payout API Documentation](/api-reference/tazapay-api/create-payout) # Checkout on Behalf Of (OBO) Source: https://developer.tazapay.com/changelog/2026/checkout-obo **Release Type:** Enhancement ## Summary Platform merchants can now create Checkout sessions and collect payments **on behalf of their sub-entities** — such as sellers, agents, wallet providers, or utility companies. This extends Tazapay's existing On Behalf Of (OBO) pattern, already available for Payouts (POBO) and Collections (COBO), into the Checkout and Payin flows. When a merchant creates a checkout with `on_behalf_of`, Tazapay validates that the entity belongs to the merchant and, depending on merchant configuration, may require the entity to be explicitly approved before the checkout can proceed. *** ## What Changed ### New fields on Checkout API The following optional fields have been added to the Checkout object (`POST /v3/checkout`, `GET /v3/checkout/{id}`): * **`on_behalf_of`** (string, optional) ID of the entity on whose behalf the checkout session is created. The entity must belong to the merchant account. Format: `ent_*`. ### New fields on Payin API When a checkout is created with `on_behalf_of`, the resulting Payin **automatically inherits** the OBO fields: * **`on_behalf_of`** (string) — Inherited from the associated checkout session. ### Webhook Updates All checkout and payin webhook events now include `on_behalf_of` in the event `data` payload when the checkout/payin was created in an OBO context. This applies to: * `checkout.created`, `checkout.paid`, `checkout.expired`, `checkout.tax_invoice_generated` * `payment_attempt.created`, `payment_attempt.failed`, `payment_attempt.processing`, `payment_attempt.succeeded` * `payin.requires_payment_method`, `payin.requires_action`, `payin.processing`, `payin.succeeded`, `payin.cancelled`, `payin.created` ## Affected Endpoints * `POST /v3/checkout` — request and response updated * `GET /v3/checkout/{id}` — response updated *** ## Compatibility No breaking changes. All new fields are optional. Existing integrations that do not send `on_behalf_of` will continue to work without modification. *** ## Relevant Links 1. [Checkout on Behalf Of Integration Guide](/cards/checkout-on-behalf-of/checkout-on-behalf-of) 2. [Checkout API Reference](/api-reference/tazapay-api/checkout) 3. [Payin API Reference](/api-reference/tazapay-api/payin) 4. [Checkout Webhook Events](/api-reference/tazapay-api/checkout-webhooks) 5. [Payin Webhook Events](/api-reference/tazapay-api/payin-webhook) # Enhancement Crypto Collections: Earlier payment visibility with new state + webhook event Source: https://developer.tazapay.com/changelog/2026/enhancement-crypto-collections-earlier-payment-visibility-with-new-state-and-webhook-event **Release type:** Enhancement (Backward-compatible) **Applies to:** Crypto / Stablecoin Collections ## What's new We've introduced a new intermediate collect state and corresponding webhook event to provide earlier visibility into stablecoin payment progress while blockchain confirmation is still pending. **Updated state flow for Crypto Wallets:** `collect.on_hold` → `collect.detected` → `collect.succeeded` or `collect.failed` ### New Collect State + Webhook Event #### `collect.detected` | Field | Value | | ------------- | ------------------ | | State | `detected` | | Webhook event | `collect.detected` | * Triggered when an inbound transaction is first detected on-chain, prior to final confirmation. * Provides early visibility while confirmations are pending. * Default subscription: **ON** ## Why we made this change Blockchain confirmations can take a few minutes depending on network conditions. This intermediate state and event improve visibility during that window without changing the final settlement timing. ## Backward compatibility This enhancement is **non-breaking**: * Existing merchants who do not consume the new states/events will continue receiving final outcomes normally. * `collect.succeeded` and `collect.failed` semantics remain unchanged. ## What hasn't changed * Final confirmation timing remains the same * Funds are credited only after full blockchain confirmation * No impact on balances, payouts, or settlement behavior # Entity API Idempotency Support Source: https://developer.tazapay.com/changelog/2026/entity-api-idempotency-support **Release Type:** Enhancement ## Summary The Entity API now supports idempotency for entity creation and updates. When a request is submitted with identifying fields that match an existing entity, the API returns the response of the first created entity. No error is returned and no duplicate entity is created. ## How It Works Duplicate detection evaluates the request against two sets of fields. **Scope fields** narrow the check to entities within the same account context: | Field | Description | | -------------- | ------------------------------------------- | | `name` | Full name of the entity | | `on_behalf_of` | Account the entity was created on behalf of | | `vertical` | Industry vertical of the entity | **Identity fields** confirm uniqueness. If the request includes an email address, national identification number, or registration number, those fields are matched globally across the account, independent of name. Fields are evaluated in priority order and the earliest-created match is returned. ### Individual entities | Priority | Field(s) | | -------- | ----------------------------------------------------------------------------------- | | 1 | `email` | | 2 | `national_identification_number.type` + `national_identification_number.number` | | 3 | `name` + `registration_address` (country, address line 1, city, state, postal code) | ### Business entities | Priority | Field(s) | | -------- | ------------------------------------------------------ | | 1 | `registration_number` + `registration_address.country` | | 2 | `name` | All field comparisons are case-insensitive and whitespace-trimmed. ## Behavior on Duplicate When a duplicate is detected, the API returns the response of the first created entity with an HTTP `200 OK`, identical to a standard successful response. No error is returned and no new entity is created. ## Affected Endpoints * `POST /v3/entity` — duplicate detection applied on creation * `PUT /v3/entity/{id}` — duplicate detection applied on update * `POST /v3/entity/{id}/submit` — duplicate detection applied on submission ## Relevant Links 1. [Entity API Documentation](/api-reference/tazapay-api/entity) # Entity Idempotency Excludes Rejected Entities Source: https://developer.tazapay.com/changelog/2026/entity-idempotency-excludes-rejected-fields **Release Type:** Enhancement ## Summary Duplicate detection for entity creation now excludes rejected entities from comparison. If an entity was previously rejected, it is no longer considered when evaluating whether an incoming request is a duplicate. A new entity will be created instead. ## How It Works Previously, idempotency checks compared incoming requests against all existing entities, including those that had been rejected. This caused requests to be incorrectly matched against rejected entities, blocking new entity creation. With this change, rejected entities are excluded from the duplicate comparison. If no non-rejected entity matches the incoming request, it is treated as new and a fresh record is created. ## Behavior | Scenario | Behavior | | -------------------------------------------------------- | ------------------------------------------ | | Incoming request matches an existing non-rejected entity | Returns existing entity with HTTP `200 OK` | | Incoming request matches only rejected entities | Creates a new entity | ## Affected Endpoints * `POST /v3/entity` — duplicate detection applied on creation * `PUT /v3/entity/{id}` — duplicate detection applied on update * `POST /v3/entity/{id}/submit` — duplicate detection applied on submission ## Relevant Links 1. [Entity API Documentation](/api-reference/tazapay-api/entity) # Entity Individual Enhancement Source: https://developer.tazapay.com/changelog/2026/entity-individual-enhancement **Release Type:** Enhancement ## Summary The Entity API has been enhanced with additional fields for individual entities. These changes cover profession details, source of funds, employment information, an expanded national identification number structure, and a transaction profile — providing a richer data model to support compliance and onboarding workflows. ## What Changed ### New fields inside `individual` object The following fields have been added to the `individual` object (applicable when `type: "individual"`): * **`profession`** (optional) * `occupation` (string) — Required if `isco_code` is not provided. Max 100 characters. * `isco_code` (string) — 4-digit ISCO occupation code. Required if `occupation` is not provided. * `industry` (string, optional) — Industry sector. Max 100 characters. * `employment_status` (enum, optional) — Values: `employed`, `self_employed`, `unemployed`, `student`, `retired`, `homemaker`, `other` * **`source_of_funds`** (optional) * `primary_source` (enum, mandatory when object is provided) — Values: `salary`, `business_income`, `investment_income`, `inheritance`, `savings`, `gift`, `pension`, `rental_income`, `sale_of_assets`, `loan`, `scholarship`, `commission`, `royalty`, `other` * `description` (string) — Required when `primary_source` is `other`. Max 500 characters. * **`employment_details`** (optional) * `employer_name` (string, mandatory) — Max 200 characters. * `designation` (string, mandatory) — Max 100 characters. * **`national_identification_number`** — expanded Previously supported only `type` and `number`. Now includes: * `issuer` (object, optional) * `country` (string) — ISO 3166-1 alpha-2 country code of the issuing country. * `state` (string) — State of the issuing authority. * `expiration` (string, optional) — Expiration date in `YYYY-MM-DD` format. * `country_of_citizenship` (string, optional) — ISO 3166-1 alpha-2 country code. * `type` enum has been expanded to include: `asylum_registration_card`, `consular_id`, `immigration_status_document`, `indigenous_card`, `insurance_card`, `international_driving_license`, `municipal_identity_card`, `national_health_id`, `postal_identity_card`, `private_operators_card`, `professional_qualification_card`, `proof_of_citizenship`, `residence_status_document`, `service_id_card`, `social_security_card`, `visa`, `voter_id`, `work_permit` ### New `transaction_profile` object (parent level) A new `transaction_profile` object has been added at the root entity level (not inside `individual`): * `monthly_expected_transactions_value` (integer, mandatory when object is provided) — Expected total value of transactions per month. * `monthly_expected_transaction_volume` (integer, mandatory when object is provided) — Expected number of transactions per month. * `expected_transaction_countries` (array of strings, mandatory when object is provided) — ISO 3166-1 alpha-2 country codes. * `expected_transaction_currencies` (array of strings, mandatory when object is provided) — ISO 4217 currency codes. * `customer_risk` (enum, mandatory when object is provided) — Values: `low`, `medium`, `high` ## Validation Rules * `individual.profession.occupation` and `individual.profession.isco_code` are mutually conditional — at least one must be provided when the `profession` object is present. * `individual.source_of_funds.description` is required when `primary_source` is `other`. * `individual.source_of_funds.primary_source` is `salary` the `employment_details` object is required. * `individual.employment_details.employer_name` and `individual.employment_details.designation` are both required when the `employment_details` object is present. * `transaction_profile` object is provided — all its fields must be present. ## Compatibility * No breaking changes. All new fields are optional or conditionally required only when their parent object is provided. * Existing integrations that do not send these fields will continue to work without modification. ### Affected endpoints * `POST /v3/entity` — request and response updated * `GET /v3/entity/{id}` — response updated * `PUT /v3/entity/{id}` — request and response updated * `POST /v3/entity/{id}/submit` — request and response updated ## Relevant Links 1. [Entity API Documentation](/api-reference/tazapay-api/entity) # Extended Document Types for Entity Submission Source: https://developer.tazapay.com/changelog/2026/extended-document-types-for-entity-submission **Release Type:** Enhancement ## Summary Tazapay is introducing five new document type values for entity creation and update — `proof_of_identity`, `proof_of_address`, `registration_documents`, `article_of_incorporation`, and `shareholder_registry`. These purpose-specific types extend the broader legacy types (e.g. `identity`, `address`, `business`) in the full-KYC entity flow and are recommended for full-verification business and individual entities going forward. The legacy types are preserved for backward compatibility. *** ## What Changed ### New Extended Document Types Five new values have been added to the `type` field accepted on entity and representative documents. These are the recommended types going forward for full-KYC entity flows: | Type | Purpose | | -------------------------- | --------------------------------------------------------------------------- | | `proof_of_identity` | Government-issued identity documents (passport, national ID, etc.) | | `proof_of_address` | Residential or operating address proof (utility bill, bank statement, etc.) | | `registration_documents` | Business registration certificates and incorporation proofs | | `article_of_incorporation` | Articles of incorporation for corporate entities | | `shareholder_registry` | Shareholder/beneficial ownership structure documentation | ### Recommended Document Types for Full-KYC Entities Full-verification entity submissions should include documents of the following types to ensure comprehensive verification coverage. #### Business Entities (Full KYC) **Entity-level documents** (attached to the business entity itself): * `registration_documents` — Business registration proof * `proof_of_address` — Operating address proof * `shareholder_registry` — Business shareholding structure **Representative documents** (attached to each representative/UBO): * `proof_of_identity` — Any government-issued identity proof (passport, national ID, driver's license, etc.) * `proof_of_address` — Address proof #### Individual Entities (Full KYC) **Entity-level documents** (attached to the individual): * `proof_of_identity` — Any government-issued identity proof (passport, national ID, driver's license, etc.) * `proof_of_address` — Recent utility bill or equivalent ## Affected Endpoints * `POST /v3/entity` — document `type` and `sub_type` enum extended * `PUT /v3/entity/{id}` — document `type` and `sub_type` enum extended *** ## Impact by Submission Method ### Dashboard Submissions Entities submitted via the Tazapay dashboard are not affected. The dashboard UI will continue to work with existing legacy entities and validation logic remains unchanged. ### API Submissions (Recommended) #### New Entity Submissions **API merchants submitting full-KYC entities should consider updating their integrations** to include the new extended document types. When creating or updating entities via the API with full-KYC verification flow: * **Business entities** should include: `registration_documents`, `proof_of_address`, `shareholder_registry` * **Individual entities** should include: `proof_of_identity`, `proof_of_address` Requests with legacy document types will continue to be accepted, but using the extended types is recommended for improved clarity and future compatibility. #### Legacy Entity Updates **API merchants with existing full-KYC entities in the system may consider updating them** to align with the new extended document type recommendations. Legacy entities lacking the new document types can be updated via the `PUT /v3/entity/{id}` endpoint to add: * **Business entities** — Entity-level documents: `registration_documents`, `proof_of_address`, `shareholder_registry` * **Representatives** — Representative-level documents: `proof_of_identity`, `proof_of_address` (for each representative/UBO) * **Individual entities** — Entity-level documents: `proof_of_identity`, `proof_of_address` This ensures API-submitted entities follow current best practices going forward. Existing entities will not be automatically updated — merchants may update both entity-level documents and all associated representative documents for business entities at their discretion. ## Compatibility **These extended document types are recommended for new entity creation via API.** Going forward, the newly introduced document types are recommended based on the entity type. The legacy types (`identity`, `business`, `address`, etc.) continue to be accepted, and entities can contain either legacy types or the extended types. **Existing (legacy) entities already in the system are not affected by this change** — the extended types serve as optional guidance for future submissions and entity updates. *** ## Relevant Links 1. [Entity API Reference](/api-reference/tazapay-api/entity) # Field Validation Updates Source: https://developer.tazapay.com/changelog/2026/field-validation-updates **Release Date:** March 24, 2026 (Tentative) **Release Type:** Enhancement · Breaking Change **Action Required** Stricter field validation will be enforced across core APIs from March 24, 2026. Review the rules below and update your integration before the release date to avoid rejected requests. These changes improve data integrity and reduce downstream payment failures by aligning validation logic with international banking and postal standards. ## 1. Banking Identifier Validation **Applies to:** * `POST /v3/beneficiary` * `PUT /v3/beneficiary/{id}` * `POST /v3/payout` **Auto-Sanitization** All banking identifier inputs are automatically sanitized before validation — spaces and hyphens are stripped and values are uppercased. ### `account_number` * **Length:** 4–34 characters * **Pattern:** `^[A-Z0-9]{4,34}$` * **Example:** `00123456789` ### `iban` * **Length:** 15–34 characters * **Pattern:** `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$` * **Structure:** * Characters 1–2 — Country code (ISO 3166-1 alpha-2) * Characters 3–4 — Check digits * Characters 5–34 — BBAN (Basic Bank Account Number) * **Additional rules:** * Country code must be valid ISO 3166-1 alpha-2, not prohibited by the Tazapay * Country code must match the destination country * Country-specific length checks are enforced (e.g., DE = 22, GB = 22, FR = 27) * Check digits are validated using the [Mod-97-10 checksum algorithm](/api-reference/appendix/iban-checksum-validation) — remainder must equal 1 * **Example:** `GB29NWBK60161331926819` ### `swift_code` * **Length:** 8 or 11 characters * **Pattern:** `^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$` * **Structure:** * Characters 1–4 — Bank code (A–Z) * Characters 5–6 — Country code (ISO 3166-1 alpha-2) * Characters 7–8 — Location code * Characters 9–11 — Branch code (optional, alphanumeric) * **Additional rules:** * Country code must be valid and not prohibited by the Tazapay * Location code `00` is rejected (reserved for test BICs) * **Example:** `DEUTDEDBXXX` ### `ifsc_code` * **Length:** Exactly 11 characters * **Pattern:** `^[A-Z]{4}0[A-Z0-9]{6}$` * **Structure:** * Characters 1–4 — Bank code (A–Z) * Character 5 — Reserved, must be literal `0` * Characters 6–11 — Branch code (alphanumeric) * **Example:** `HDFC0004832` ### `aba_code` * **Length:** Exactly 9 digits * **Pattern:** `^[0-9]{9}$` * **First 2 digits must fall within:** 00–12, 21–32, 61–72, or 80 * **Checksum:** Validated using the [ABA 3-7-1 checksum algorithm](/api-reference/appendix/aba-routing-number-validation) — result must be divisible by 10 (modulo 10 = 0) * **Example:** `021000021` ### `sort_code` * **Length:** Exactly 6 digits * **Pattern:** `^[0-9]{6}$` * **Example:** `608371` ### `bsb_code` * **Length:** Exactly 6 digits * **Pattern:** `^[0-9]{6}$` * **Example:** `063000` ### `bank_code` * **Length:** 3 digits (COMPE) or 8 digits (ISPB) * **Pattern:** `^([0-9]{3}|[0-9]{8})$` * **Applicability:** Brazil (BR) only * **Example:** `00000341` ## 2. Address, Postal Code & Phone Validation **Applies to:** * `POST /v3/beneficiary` * `PUT /v3/beneficiary/{id}` * `POST /v3/customer` * `PUT /v3/customer` * `POST /v3/customer/{customer_id}/{address_type}` * `POST /v3/checkout` ### Address Text Fields — `line1`, `line2`, `city`, `state` The following special characters are **not permitted** in address text fields: ``` < > { } | \ ^ ` = ``` **Note** These fields are optional. Validation applies only when a value is provided. ### `postal_code` * **Length:** 3–12 characters * **Pattern:** `^[A-Za-z0-9 -]+$` * **Allowed characters:** A–Z, a–z, 0–9, spaces, hyphens (-) * Must contain at least one alphanumeric character. Values with only spaces or symbols are rejected. * **Example:** `94105-1234` ### `calling_code` + `number` (Phone) * `calling_code` and `number` must always be provided **together**. Supplying only one returns a validation error. * `calling_code` must begin with `+` followed by a valid country dialing code (e.g., `+1`, `+65`) * **Combined digit length** excluding the `+`: 7–15 digits (E.164 standard) **Valid examples:** | calling\_code | number | | ------------- | ------------ | | `+65` | `91234567` | | `+1` | `2025550123` | ## 3. Name Field Validation **Applies to:** * `POST /v3/entity` * `PUT /v3/entity/{entity_id}` ### `name` * **Allowed characters:** A–Z, a–z, 0–9, spaces, `&`, `,`, `.`, `-` * **Pattern:** `^[a-zA-Z0-9][a-zA-Z0-9 &,.-]*$` * **Examples:** `ABC Trading, Ltd.`, `Smith & Sons` ## Relevant Links 1. [Beneficiary API Documentation](/api-reference/tazapay-api/beneficiary) 2. [Create Payout API Documentation](/api-reference/tazapay-api/create-payout) 3. [Customer API Documentation](/api-reference/tazapay-api/user) 4. [Entity API Documentation](/api-reference/tazapay-api/entity) 5. [Checkout API Documentation](/api-reference/tazapay-api/checkout) # Introduction of Payout Reversal – Sandbox Source: https://developer.tazapay.com/changelog/2026/introduction-of-payout-reversal-sandbox The payout reversal feature is now also available in the sandbox environment for testing payout reversal scenarios end-to-end. ## New State Introduced for Sandbox Payout * **`reversed`** Indicates that a previously succeeded payout has been successfully reversed. ## Amount-Based Reversal Scenarios The payout reversal feature in sandbox supports two distinct amount-based reversal scenarios: ### Scenario 1: Payout amounts between 500,000 and 550,000 | Attribute | Details | | ------------- | ------------------------ | | Payout status | `succeeded` → `reversed` | | FX Impact | None | | Fees | Tazapay fee only | ### Scenario 2: Payout amounts between 550,000 and 600,000 | Attribute | Details | | ------------- | ----------------------------------------------------------- | | Payout status | `succeeded` → `reversed` | | FX Impact | Significant (difference in currency conversion) | | Fees | Tazapay fee, FX impact charges and third-party fees applied | ## Reversal Details The payouts are reversed with the following details: | Field | Value | | ------------- | ------------------------------------- | | Reason | Invalid or closed beneficiary account | | Reversal Code | `PR1001` | ## Relevant Links 1. [Payout Reversals](/changelog/2025/introduction-of-payout-reversal) 2. [Reversal Reason Codes](/api-reference/appendix/payout-reversal-reasons) # Fetch bank information from Global Bank Directory Source: https://developer.tazapay.com/changelog/2026/list-banks-from-global-bank-directory # Purpose The API enables users to get bank information from our internal Global Bank Directory on the basis of local codes, swift codes and bank name. # API Signature ## Endpoint /v3/payout/bank ## Query Paramaters country: valid country code code\_type: the code on the basis of which user would like to search. It must be one of the following: * swift\_code * sort\_code * aba\_code * bsb\_code * ifsc\_code * iban * bank\_name search\_text: code value or name of the bank ## Examples * Match on swift code ```bash theme={null} curl --location --get 'https://api-sandbox.tazapay.com/v3/payout/bank' \ --data-urlencode 'country=AU' \ --data-urlencode 'code_type=swift_code' \ --data-urlencode 'search_text=BKCHAU2AP' ``` ```json theme={null} { "status": "success", "message": "", "data": { "has_more": false, "object": "list", "results": [ { "address": { "city": "SYDNEY", "country": "AU", "line1": "", "line2": "", "postal_code": "2000", "state": "NSW" }, "bank_codes": { "bsb_code": "980202", "swift_code": "BKCHAU2APAR" }, "bank_name": "BANK OF CHINA (AUSTRALIA) LIMITED", "country_code": "AU", "id": "bke_d7ag8hfhambilrokaoog", "matched_on": { "swift_code": "BKCHAU2APAR" }, "object": "bank" }, { "address": { "city": "PERTH", "country": "AU", "line1": "", "line2": "", "postal_code": "6000", "state": "WA" }, "bank_codes": { "bsb_code": "980600", "swift_code": "BKCHAU2APTH" }, "bank_name": "BANK OF CHINA (AUSTRALIA) LIMITED", "country_code": "AU", "id": "bke_d7ag8h7hambilrok50bg", "matched_on": { "swift_code": "BKCHAU2APTH" }, "object": "bank" } ] } } ``` # Payin Reversal: Risk-Driven Reversed State and Webhook Events Source: https://developer.tazapay.com/changelog/2026/payin-reversal-new-reversed-state **Release type:** Enhancement (Backward-compatible) **Applies to:** Payin, Payment Attempt ## What's new A new terminal state **`reversed`** has been introduced for Payin and Payment Attempt objects. This state is triggered by an **automated payer name verification check** run after PSP payment approval on eligible push-based Alternative Payment Methods (APMs). When the name provided by the buyer at checkout does not match the name returned by the PSP after payment (a `NO_MATCH` result), the transaction is moved to `reversed` and a full refund is automatically initiated back to the buyer. The net impact on the merchant balance is zero. *** ## Why this was introduced Push-based APMs (PayNow, PIX, UPI, Promptpay, etc.) debit funds immediately, and the payer's identity is only confirmed after PSP approval. This creates exposure to social-engineering fraud where a payment is made by a third party on behalf of the buyer. The `reversed` state is Tazapay's automated response to this pattern — transactions where the payer identity cannot be verified are reversed before they reach `succeeded`. *** ## Eligibility The name match check — and therefore the `reversed` state — only applies when **all** of the following conditions are true: * The payment method is a push-based APM in Tazapay's risk-check allowlist * The PSP returns a `payer_name` in its success response * The merchant has **Name Match Check enabled** (configured via the Tazapay Ops dashboard) * The customer's total payin volume over the trailing 30 days exceeds the configured threshold (default: **0 USD**, meaning the check applies to every eligible transaction) Transactions that do not meet all conditions proceed directly to `succeeded` with no change to the existing flow. *** ## Updated Payin State Flow After PSP approval, an internal risk check runs between `processing` and the terminal state. This check is not visible as a separate state — it completes within seconds. ``` processing → succeeded Name match: FULL_MATCH, PARTIAL_MATCH processing → reversed Name match: NO_MATCH (refund auto-initiated) ``` `reversed` is a terminal state. A payin that reaches `reversed` will never emit `payin.succeeded`. *** ## Name Match Outcomes | Match Result | Terminal State | Outcome | | --------------- | -------------- | ---------------------------------------------- | | `FULL_MATCH` | `succeeded` | Normal flow — funds credited to merchant | | `PARTIAL_MATCH` | `succeeded` | Normal flow — funds credited to merchant | | `NO_MATCH` | `reversed` | Refund initiated — net merchant impact is zero | *** ## Balance & Fee Impact for `reversed` Transactions Funds flow through the merchant balance even for `reversed` transactions to maintain ledger consistency: 1. **Payin credit** — merchant balance is credited (same as `succeeded`) 2. **Refund debit** — full amount is immediately debited back via a system-initiated refund The net merchant balance impact is **zero**. Tazapay bears both the payin processing fee and the refund processing fee — no fees are charged to the merchant or the buyer. *** ## Automatic Refund When a payment attempt is reversed, Tazapay automatically creates a refund and initiates it with the PSP. Merchants do not need to take any action. The refund is created with: | Field | Value | | -------------- | ---------------- | | `source` | `payin_reversal` | | `reason` | `Payin Reversal` | | `initiated_by` | `system` | | `fee_bearer` | `tazapay` | Merchants will receive a **`refund.created`** webhook immediately after the refund is saved. The refund ID is only available in that webhook payload — it is not included in the `payment_attempt.reversed` payload or the Get Payin response. Merchants should capture the `refund.id` from `refund.created` to track the refund status via `GET /v3/refund/{refund_id}`. *** ## Notifications | Recipient | Channel | Configurable | | --------- | ------------------------------------ | --------------------------------------------------------- | | Buyer | Email | No — always sent | | Merchant | Email | Yes — requires email event to be enabled at account level | | Merchant | Webhook (`payment_attempt.reversed`) | Yes — enabled by default | The buyer receives an email notifying them that their payment was reversed and a full refund has been initiated. The merchant email (if enabled) includes the transaction amount, buyer details, and a link to view the transaction in the dashboard. *** ## Webhook Events | Event | Trigger | New? | Default (on/off) | | -------------------------- | ---------------------------------------------- | ------------------- | ---------------- | | `payment_attempt.reversed` | Payment attempt `status` changes to `reversed` | Yes | On | | `refund.created` | Refund created for the reversed payment | No — existing event | Off | *** ## API Changes ### Get Payin — `GET /v3/payin/{id}` Two new fields have been added to the response: | Field | Type | Description | | ----------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | | `reversed_at` | string (ISO timestamp) | Timestamp when the payin was reversed. `null` unless `status` is `reversed`. | | `risk_check` | object / null | Risk check result that determined the terminal state. `null` when no name match check was performed. | | `risk_check.result` | string | Match outcome: `FULL_MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, or `EMAIL`. | | `risk_check.buyer_name` | string | Name provided by the buyer at checkout. | | `risk_check.payer_name` | string | Name returned by the PSP after payment. | | `risk_check.checked_at` | string (ISO timestamp) | Timestamp when the risk check was performed. | *** ## Backward Compatibility This enhancement is **non-breaking**: * Transactions on payment methods not in the APM allowlist, or for merchants without Name Match Check enabled, continue to flow directly to `succeeded` — no change. * `succeeded` and `cancelled` state semantics and flows are unchanged. * `reversed_at` is `null` in the response for payins that are not in `reversed` status. `risk_check` is `null` for payins that were not subject to a name match check. * `payment_attempt.reversed` is a new webhook event type, enabled by default. Merchants who have configured a webhook endpoint will begin receiving it automatically. # Payout Failure Code in Fetch Payout Source: https://developer.tazapay.com/changelog/2026/payout-failure-code-in-fetch-payout # Payout Object Changes The **Payout object** has been enhanced to include a new **`failure`** object in the response. This provides more structured and cleaner failure information when a payout has failed, making it easier to programmatically identify and handle failure scenarios. We will be deprecating the old failure codes that were populated in the `status_description` field soon. It is recommended to consume these new failure codes instead. ## New Field Added * **`failure`** An object that contains details about why a payout failed. This field is `null` for payouts that have not failed. | Field | Type | Description | | ------------- | ------ | -------------------------------------------------------------------------------------------------------------- | | `code` | string | Error code indicating the reason for the payout failure | | `description` | string | Human-readable description of the [**failure reason**](/api-reference/appendix/payout-failure-reasons-updated) | The `failure` object is only populated when the payout status is `failed`. For all other statuses (e.g., `succeeded`, `processing`, `reversed`), this field will be `null`. ## Example Response (Failed Payout) ```json theme={null} { "status": "success", "message": "", "data": { "amount": 100000, "balance_transaction": "btr_d35pv4qcl8imrv60", "beneficiary": "bnf_d3inm6ami8u10oqfg", "beneficiary_details": { "address": { "country": "CN", "line1": "Zhen Rui Yun Lu 66", "postal_code": "311011" }, "destination_details": { "bank": { "account_number": "33050167624000001030", "account_type": "", "bank_codes": { "swift_code": "PCBCCNBJZJX" }, "bank_name": "CHINA CONSTRUCTION BANK, ZHEJIANG BRANCH", "country": "CN", "currency": "USD", "transfer_type": "swift" }, "type": "bank" }, "email": "", "name": "IMPORT AND EXPORT CO., LTD", "type": "business" }, "charge_type": "ours", "created_at": "2025-09-18T10:07:35.101708Z", "currency": "USD", "holding_currency": "USD", "holding_fx_transaction": { "exchange_rate": 1, "final": { "amount": 100000, "currency": "USD" }, "id": "fx_d35tjpnfigp2dt2hgg", "initial": { "amount": 100000, "currency": "USD" }, "object": "fx_transaction" }, "id": "pot_d35tjpn4qcl8iv30", "local": { "fund_transfer_network": "swift" }, "logistics_tracking_details": [], "metadata": null, "mt103": "", "object": "payout", "on_behalf_of": "", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 100000, "currency": "USD" }, "id": "fx_d35tfigo4p2dt2hh0", "initial": { "amount": 100000, "currency": "USD" }, "object": "fx_transaction" }, "purpose": "PYR003", "reference_id": "INV-CN-2025-0042", "statement_descriptor": "Payment for goods", "status": "failed", "status_description": "PO1012", "failure": { "code": "PF020101", "description": "Bank identification code is missing/invalid" }, "tracking_details": null, "transaction_description": "Payment for goods acc 125", "type": "swift" } } ``` ## Example Response (Successful Payout) ```json theme={null} { "status": "success", "message": "", "data": { "amount": 3000000, "balance_transaction": "btr_dhuvflvi5frlneafr0", "beneficiary": "bnf_d0dla9u8dpp4edio0", "beneficiary_details": { "address": null, "destination_details": { "bank": { "account_type": "", "bank_codes": { "swift_code": "FBDEFF" }, "bank_name": "ER VOLKSBANK EG", "country": "DE", "currency": "EUR", "iban": "DE535019045650474185", "transfer_type": "any" }, "type": "bank" }, "email": "", "name": "GMBH", "type": "business" }, "charge_type": "", "created_at": "2025-09-16T08:27:41.832790Z", "currency": "EUR", "holding_currency": "USD", "holding_fx_transaction": { "exchange_rate": 0.846438, "final": { "amount": 3000000, "currency": "EUR" }, "id": "fx_d34flc7loipp34fmg", "initial": { "amount": 3544266, "currency": "USD" }, "object": "fx_transaction" }, "id": "pot_d34hlvi5frlneafo0", "local": { "fund_transfer_network": "sepa" }, "logistics_tracking_details": [], "metadata": null, "mt103": "", "object": "payout", "on_behalf_of": "", "payout_fx_transaction": { "exchange_rate": 1, "final": { "amount": 3000000, "currency": "EUR" }, "id": "fx_d34huvflc7pp34fm0", "initial": { "amount": 3000000, "currency": "EUR" }, "object": "fx_transaction" }, "purpose": "PYR001", "reference_id": "DE-LOG-2024-0909", "statement_descriptor": "Logistics Payment", "status": "succeeded", "status_description": "", "failure": null, "tracking_details": { "tracking_number": "098771252590P9A", "tracking_type": "UTR" }, "transaction_description": "Payment for logistic services 9-09", "type": "local" } } ``` # Payout Webhook Changes The **`payout.failed`** webhook event now includes the same **`failure`** object in its payload. When a payout fails, the webhook response will contain the `failure` object with `code` and `description` fields, providing structured failure details alongside the existing `status_description`. ## Example Webhook Payload (payout.failed) ```json theme={null} { "id": "evt_d35tjpn4qcl8iv31", "type": "payout.failed", "created_at": "2025-09-18T10:15:22.304512Z", "data": { "amount": 100000, "balance_transaction": "btr_d35pv4qcl8imrv60", "beneficiary": "bnf_d3inm6ami8u10oqfg", "beneficiary_details": { "address": { "country": "CN", "line1": "Zhen Rui Yun Lu 66", "postal_code": "311011" }, "destination_details": { "bank": { "account_number": "33050167624000001030", "bank_codes": { "swift_code": "PCBCCNBJZJX" }, "bank_name": "CHINA CONSTRUCTION BANK, ZHEJIANG BRANCH", "country": "CN", "currency": "USD", "transfer_type": "swift" }, "type": "bank" }, "email": "", "name": "IMPORT AND EXPORT CO., LTD", "type": "business" }, "created_at": "2025-09-18T10:07:35.101708Z", "currency": "USD", "id": "pot_d35tjpn4qcl8iv30", "local": { "fund_transfer_network": "swift" }, "object": "payout", "purpose": "PYR003", "reference_id": "INV-CN-2025-0042", "statement_descriptor": "Payment for goods", "status": "failed", "status_description": "PO1012", "failure": { "code": "PF020101", "description": "Bank identification code is missing/invalid" }, "tracking_details": null, "transaction_description": "Payment for goods acc 125", "type": "swift" } } ``` ## Relevant Links * [**GET Payout**](/api-reference/tazapay-api/fetch-payout) * [**Payout Webhooks**](/api-reference/tazapay-api/payout-webhooks) * [**Payout Failure Reason Codes**](/api-reference/appendix/payout-failure-reasons-updated) # Payout Initiator Bank Hold Webhook Event Source: https://developer.tazapay.com/changelog/2026/payout-initiator-bank-hold-webhook-event # Payout Initiator Bank Hold Webhook Event **Release Type:** Enhancement A new payout webhook event, `payout.initiator_bank_hold`, has been introduced to notify merchants when a payout is placed on hold by the initiating bank for review. During this state, the payout amount is reserved from the available balance and will be released or processed once the transaction is cleared by the bank. ## What Changed? ### New Webhook Event The following webhook event has been added to the Payout webhook lifecycle: | Event | Description | Default | | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `payout.initiator_bank_hold` | Triggered when the payout is placed on hold by the initiating bank for review and will be released once the transaction is cleared by the bank. | On | ### New Payout Status A new payout status value has been introduced: | Status | Description | | :-------------------- | :-------------------------------------------------------------------------------------- | | `initiator_bank_hold` | Indicates that the payout is temporarily on hold by the initiating bank pending review. | ## Compatibility This is a non-breaking change. Existing integrations will continue to function without modification. Merchants consuming payout webhook events should update their integrations to support the new `initiator_bank_hold` payout status and `payout.initiator_bank_hold` event type. ## Relevant Links * [Payout Overview](/api-reference/tazapay-api/payout) * [Payout Webhooks](/api-reference/tazapay-api/payout-webhooks) * [Fetch Payout](/api-reference/tazapay-api/fetch-payout) # Person ID Support For Entity Representatives Source: https://developer.tazapay.com/changelog/2026/person-id-support-for-entity-representatives **Release Type:** Enhancement ## Summary The Entity API now supports a `person_id` field in the `representatives` object. This field uniquely identifies each representative and must be included when updating existing representatives to maintain identity consistency for ongoing sanction screening. ## What Changed * **New `person_id` field on representatives** * A `person_id` (string) field has been added to the `representatives` object across all Entity API endpoints. * Example value: `psn_d3iv85v58tg9dlpipu3g` * **Affected endpoints** * `POST /v3/entity` — response now includes `person_id` for each representative * `GET /v3/entity/{id}` — response now includes `person_id` for each representative * `PUT /v3/entity/{id}` — accepts `person_id` in the request body; response includes it * `POST /v3/entity/{id}/submit` — response now includes `person_id` for each representative * **Update Entity now accepts full representative details** * The `PUT /v3/entity/{id}` endpoint now accepts the complete `representatives` array in the request body, including `person_id`, personal details, address, phone, roles, and documents. **Action Required for Entity Updates** When updating an entity with existing representatives, you **must** include the `person_id` of each existing representative in the request payload. This ensures the representative's identity is preserved for ongoing sanction screening. The `person_id` can be retrieved from the Fetch Entity (`GET /v3/entity/{id}`) response. ## Compatibility * No breaking changes for existing integrations. * The `person_id` field is additive and can be safely ignored by clients that do not use it. * Existing representatives without `person_id` in update requests will be treated as new representatives, which may trigger a new sanction screening cycle. ## Relevant Links 1. [Entity API Documentation](/api-reference/tazapay-api/entity) # Entity Status & Purpose-of-Use Validation for OBO Payout Creation Source: https://developer.tazapay.com/changelog/2026/q3/august/obo-payout-entity-status-validation **Release Type:** Enhancement · Breaking Change **Action Required** Starting August 2026, Create Payout will reject requests made **on behalf of (OBO)** an entity whose details are still in draft (not submitted), or whose `purpose_of_use` does not include `payout`. Before this rolls out, check the `approval_status` and `purpose_of_use` of every entity you use as an OBO party, and update your integration to handle the new rejection responses gracefully. ## Summary Tazapay's On-Behalf-Of (OBO) payouts let a platform merchant move funds on behalf of an entity — a seller, agent, or partner it onboards. Until now, Create Payout did not check whether that entity's details had actually been submitted, or whether the entity was even meant to be used for payouts, before releasing funds on its behalf. To close this gap, Create Payout now runs two checks on the entity before creating an OBO payout: 1. The entity's details must have been submitted — not still in draft. 2. The entity's `purpose_of_use` must explicitly include `payout`. If either check fails, the payout is not created and the API returns an error explaining why. ## What Changed ### Entity Status Check The entity's `approval_status` must be one of: * `approved` * `submitted` * `requires_action` These statuses all mean the entity's details have, at minimum, been submitted. An entity that's still in draft (details not yet submitted) can no longer be used as the OBO party for a payout. ### Purpose-of-Use Check An entity's `purpose_of_use` determines what it can be used for: `payout` is required to create a payout on its behalf, `collect` to create a collection, and so on. The entity's `purpose_of_use` array must include `payout` to be used as the OBO party on a Create Payout call, even if its status otherwise qualifies. ## Affected Endpoints * `POST /v3/payout` — when the request specifies an on-behalf-of entity. ## Compatibility This is a **breaking change for OBO payout callers only**. Create Payout calls that do not act on behalf of an entity are unaffected. If you use OBO payouts today, requests for entities still in draft, or without `payout` in `purpose_of_use`, will start failing. ## Behavior | Scenario | Result | | ------------------------------------------------------------------------------------------------------ | --------------------------- | | Entity status is `approved`, `submitted`, or `requires_action`, and `purpose_of_use` includes `payout` | Payout is created | | Entity is still in draft (details not submitted) | Payout creation is rejected | | Entity status qualifies, but `purpose_of_use` does not include `payout` | Payout creation is rejected | ## Relevant Links 1. [Create Payout API Documentation](/api-reference/tazapay-api/create-payout) 2. [Entity API Documentation](/api-reference/tazapay-api/entity) 3. [Checkout on Behalf Of Integration Guide](/cards/checkout-on-behalf-of/checkout-on-behalf-of) # Entity ID Support in Payout Quote Creation Source: https://developer.tazapay.com/changelog/2026/q3/july/entity-id-support-in-payout-quote-creation # Create Payout Quote API Changes We have added support for passing an `entity_id` when creating a payout quote. This lets merchants associate a payout quote with a specific entity at the time of quote creation. ## Why This Matters * **Entity-level association** – Payout quotes can now be tied to a specific entity, giving clearer traceability for entity-scoped payout flows. ## Impact on Existing Flows The `entity_id` field is optional. Existing payout quote flows continue to work as before, and this new field is available without breaking current integrations. ## Relevant Links * [**Create Payout Quote**](https://developer.tazapay.com/api-reference/tazapay-api/create-payout) # Support for Holding Amount–Based Payout Quote Creation Source: https://developer.tazapay.com/changelog/2026/support-for-holding-amount-based-payout-quote-creation # Create Payout Quote API Changes We have enhanced payout quotes to support holding amount–driven quote creation, allowing merchants to define the payout amount in any one of the available holding (balance) currencies while Tazapay automatically derives the final payout amount after deducting fees. This gives more control when the primary reference amount is the holding amount rather than the destination or payout amount. ## Why This Matters * **Better control over balances** – Ideal for scenarios where merchants want to fully utilise or precisely cap the use of their holding balance for a payout. * **Reduced manual calculations** – No need to pre-calculate net payout amount after fees; Tazapay handles this automatically from the holding amount. * **Fewer payout failures** – Built-in validation reduces payout errors caused by insufficient funds once fees are applied. ## Impact on Existing Flows Existing payout quote flows that use payout amount or destination amount continue to work as before, and this new holding amount option is available without breaking current integrations. ## Relevant Links * [**Create Payout Quote**](/api-reference/tazapay-api/create-payout-quote) # SWIFT GPI Tracking Source: https://developer.tazapay.com/changelog/2026/swift-gpi-tracking SWIFT GPI Tracking is now available for all eligible SWIFT payouts processed by Tazapay. * New webhook event `payout.gpi_tracking` — fired on every GPI hop, carries latest status and full cumulative timeline. Does not modify `payout.status`. * GPI status codes with Tazapay's normalised model: `ACSP/G000–G004` (IN\_TRANSIT), `ACSC` (DELIVERED), `ACCC` (CREDITED), `RJCT/OTHERS` (REJECTED). * No backward-incompatible changes to existing payout API responses. All new fields are additive. * Existing SWIFT payouts without a stored UETR will not be retro-tracked. * GET API support coming soon. ## Relevant Links * [**SWIFT GPI Tracking**](/api-reference/tazapay-api/swift-gpi-tracking) * [**Payout Webhooks**](/api-reference/tazapay-api/payout-webhooks) # Stablecoins Source: https://developer.tazapay.com/collection-accounts/coverage/stablecoins | Stablecoin | Supported Chains | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | USDC USDC | Ethereum, Solana, Algorand, Arbitrum, Avalanche, Base, Flow, Hedera, Near, Noble, OP Mainnet, Polkadot, Polygon, Stellar, Tron | | USDT USDT | Ethereum, Tron, Polygon, Solana | # Virtual Accounts Source: https://developer.tazapay.com/collection-accounts/coverage/virtual-accounts Every market, currency, and rail you can collect on with a Tazapay virtual account
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------- | ------------------- | | SGD | T+1 | FAST | 200,000 SGD | | | | MEPS | 60,000,000 SGD | Wire Transfer (SWIFT) **Setup time** - T+1
**Currencies** - JPY, AUD, HKD, CNH, USD, SGD, CAD, GBP, EUR, CHF, DKK, NOK, SEK, NZD
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------------ | ------------------- | | EUR | Instant | SEPA Instant | 100,000 EUR | | | | SEPA | 40,000,000 EUR | | GBP | Instant | CHAPS | 35,000,000 GBP | | | | FAST | 1,000,000 GBP | Wire Transfer (SWIFT) **Setup time** - Instant
**Currencies** - USD, EUR, GBP, SGD, AED, HKD, JPY, KWD, NZD, OMR, QAR, SAR, THB, TRY, BGN, BHD, CHF, CZK, DKK, HUF, ILS, KES, NOK, PLN, RON, SEK
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------- | ------------------- | | USD | Instant | ACH | 5,000,000 USD | | | | Fedwire | 5,000,000 USD | Wire Transfer (SWIFT) **Setup time** - T+1
**Currencies** - USD
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------- | ------------------- | | CAD | Instant | EFT | 65,000,000 CAD |
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------- | ------------------- | | AUD | Instant | NPP | 75,000,000 AUD |
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------------ | ------------------- | | EUR | Instant | SEPA Instant | 100,000 EUR | | | | SEPA | 40,000,000 EUR | | | | TIPS | 40,000,000 EUR |
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------- | ------------------- | | DKK | Instant | Kronos2 | 300,000,000 DKK | Wire Transfer (SWIFT) **Setup time** - Instant
**Currencies** - GBP, AED, USD, EUR, SGD, TRY, AUD, DKK
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------- | ------------------- | | AED | Instant | IPP | 180,000,000 AED | | | | FPS | 50,000 AED |
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | ------- | ------------------- | | NGN | Instant | NIBSS | 100,000,000 NGN |
Local Bank Transfer | Currency | Setup Time | Network | Max per Transaction | | -------- | ---------- | -------- | ------------------- | | PHP | Extended | InstaPay | 50,000 PHP | | | | PESONet | 2,800,000,000 PHP |
* There is no minimum transaction amount on local rails. * Minimum and maximum transaction limit for SWIFT incoming payments is 10 USD and 50,000,000 USD respectively. # Disabling via API Source: https://developer.tazapay.com/collection-accounts/disabling-va/api Disable a Collection Account programmatically using the Tazapay API To close (disable) a collection account, call the [Disable Collection Account API](/api-reference/tazapay-api/disable-collection-account). Once a disablement request is submitted: * The account status remains `enabled` while the request is in progress. * Webhook events are sent as the request moves through each state. * On success, the account transitions to `disabled` and will no longer accept incoming payments. To cancel an in-progress disablement request, use the [Cancel Collection Account Request API](/api-reference/tazapay-api/cancel-collection-account-request). > Stablecoin Wallets once created cannot be disabled. Once disabled, a collection account cannot be re-enabled unless the `account_reenablement_supported` field on the collection\_account object is `true`. *** ## Webhook Events Subscribe to the [`collection_account.*` webhook events](/api-reference/tazapay-api/collection-account-webhooks) to track the disablement lifecycle. *** ## Other ways to disable * [Disable via Dashboard](/collection-accounts/disabling-va/dashboard) - disabling a collection account from the Tazapay dashboard. # Disabling via Dashboard Source: https://developer.tazapay.com/collection-accounts/disabling-va/dashboard Disable a Collection Account from the Tazapay dashboard Once disabled, an account stops accepting incoming payments. Stablecoin Wallets cannot be disabled. Once a disablement request is submitted: * The account status remains `enabled` while the request is in progress. * On success, the account transitions to `disabled` and will no longer accept incoming payments. *** ## Disabling a Collection Account Go to **Collection Accounts** in the left navigation panel and open the **Virtual Accounts** tab. Click on the account to open its details page. Click the **Close Account** button on the account details page. Confirm the action in the dialog that appears. The account status will update to `disabled` once the disablement request is processed. Once disabled, a collection account cannot be re-enabled unless it explicitly supports re-enablement. Contact [support@tazapay.com](mailto:support@tazapay.com) for assistance. *** ## Other ways to disable * [Disable via API](/collection-accounts/disabling-va/api) - disabling a collection account programmatically. # Fetch Collect Details via API Source: https://developer.tazapay.com/collection-accounts/incoming-payments/api Retrieve incoming collect details programmatically You can use the [Fetch Collect API](/api-reference/tazapay-api/fetch-collect) to retrieve the details of an incoming collect payment by its ID. For the full field-level schema, see the [Collect object reference](/api-reference/tazapay-api/collects). *** ## Other ways to track incoming payments Beyond polling the API, you can monitor collects visually or have Tazapay push updates to you. Browse, filter, and reconcile collects manually — no integration required. Receive a real-time event the moment funds land, so you don't have to poll. # Fetch Collect Details via Dashboard Source: https://developer.tazapay.com/collection-accounts/incoming-payments/dashboard View incoming collects on the [Tazapay dashboard](https://dashboard.tazapay.com/) ## Accessing Transactions * Once logged in, click on the `Transactions` tab located on the left-hand side vertical navigation bar. * A listing screen will appear displaying the following columns: * Payment ID: A unique identifier for each collect, starts with `col_` * Status: The status of the collect - succeeded, failed or on\_hold * Invoice Amt: The amount in the currency collected * Date: The timestamp at which the collect was created * Payment Method: Indicates whether the collect was made using Local Bank Transfer, Wire Transfer or via Stablecoins. collections-listing ## Searching for collection records Use the search tab at the top-left corner of the screen to find a specific collect ID. You can perform a full search with the exact ID or a partial search with a part of the ID. ## Viewing Collect Details To view the expanded details for a collect, you can simply click on the Payment ID starting with `col_` on the `Transactions` screen and it will redirect you to the collection summary screen. The screen will display the following information - ### Account Details | Fields | Description | | --------------- | ------------------------------------------------------ | | Account ID | Unique Tazapay Account ID for your registered business | | Account Email | User Email | | Account Country | Business Registration Country | | Business Name | Registered Name of your business | ### Collection Details | Fields | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------- | | Collection Amount | The amount credited for the payment | | Fees | Tazapay Fees for the payment | | Payment Method | The payment method (Local Bank Transfer or Wire Transfer or Stablecoin) | | Receiving Account Number / IBAN | The account number (or IBAN in case the currency is EUR) of the receiving account for the payment | | Status | The status of the collect - its usually `succeeded`. Rarely can be `on_hold` or `failed` | | Transaction Hash | Unique identifier assigned to this blockchain transaction | ### Sender details Sender details vary by the payment method used to fund the payment. These fields are populated only if the sender enters them in the banking application used to transfer the funds. Any of them may be empty. | Field | Description | | ------------------------ | ----------------------------------------------------- | | `name` | Name of the sender | | `bank` | Details of the bank account the payment was sent from | | `reference` | Reference entered by the sender | | `additional_information` | Free-text details entered by the sender | | Field | Description | | ----------------- | ---------------------------------------------- | | `deposit_address` | Sender's address on the blockchain | | `type` | Wallet or blockchain used, e.g. Ethereum, Tron | *** ## Next steps Poll the API to retrieve incoming payments and their sender details. Get notified the moment funds land, instead of polling. # FX Source: https://developer.tazapay.com/collection-accounts/incoming-payments/fx How incoming collects are held and when currency conversion happens When funds arrive in a Collection Account, what happens next depends on whether the **incoming currency** matches one of your **holding currencies** on your Tazapay balance. | Scenario | Outcome | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Incoming currency **is** a holding currency | Funds are credited and held in the same currency. No conversion takes place. | | Incoming currency **is not** a holding currency | The funds are converted to your **primary holding currency** at Tazapay's prevailing FX rate and credited in that currency. | This means you can choose to hold balances in the same currencies you collect in or consolidate everything into a single primary currency. *** ## Managing Your Holding Currencies You can configure which currencies you want to hold on your Tazapay balance. See: See your current balances across currencies. Add new holding currencies to your balance. *** ## Tracking FX on Collects When an incoming collect is converted, the FX details are captured on the resulting balance\_transaction. The `balance_transaction` will be present on the [collect object](/api-reference/tazapay-api/collects). See the [FX Transaction object](/api-reference/tazapay-api/fx-transaction-object) for the field-level schema and [Balance Transactions](/api-reference/tazapay-api/balance-transaction) for tracking and reconciliation. # Holds Source: https://developer.tazapay.com/collection-accounts/incoming-payments/holds How Tazapay screens incoming collects and when payments are placed on hold Any incoming collect is screened against Tazapay's compliance and risk rules. If a payment gets flagged, it is moved to an `on_hold` state. While a collect is on hold: * Funds are not yet credited to your balance. A `balance_transaction` object is not created. * You will not see the collect as `succeeded`. * You may be reached out for additional information. The collect will transition either to `succeeded` (funds credited) or `failed` (funds returned via a [reversal](/collection-accounts/incoming-payments/reversals)). *** ## Subscribing to Compliance Hold Events You can subscribe to the [`collect.on_hold` webhook event](/api-reference/tazapay-api/collect-webhook#collect-on_hold) to be notified when a collect is placed on a compliance hold. This is useful for: * Pausing downstream order fulfillment until the collect clears. * Alerting your operations team to follow up with the customer. * Reconciling delayed credits in your books. *** ## See Also How a collect moves between states, including holds. What happens if a held collect ultimately fails. # Introduction Source: https://developer.tazapay.com/collection-accounts/incoming-payments/introduction A [collect](/api-reference/tazapay-api/collects) represents an incoming payment received into a Collection Account A [collect](/api-reference/tazapay-api/collects) represents a single incoming payment whether received via local rail, SWIFT, or stablecoin transfer. Each collect captures the amount, currency, sender details (where available), the receiving account or wallet, the [on behalf of](/collection-accounts/integration-guides/collections-on-behalf-of) entity ID, and the transaction's current state. Collects are created automatically by Tazapay as funds arrive. You can subscribe to [webhook events](/api-reference/tazapay-api/collect-webhook) to be notified of new collects in real time, and use the dashboard or API to inspect each one. For the full structure of the object and every state it can move through, see the API reference: Full field-level reference for the Collect object, with examples. Every state a collect can move through, and what triggers each transition. *** ## What's Next Retrieve collect details via API, Dashboard, or Webhooks. How Tazapay screens incoming payments for compliance. What happens when a collect fails and funds are returned. How incoming funds are held, and when conversion happens. # Reconciliation Source: https://developer.tazapay.com/collection-accounts/incoming-payments/reconciliation Reconcile collects against a settlement using balance transactions Every settlement you receive can be made up of one or more collects. To reconcile a settlement, fetch the collects associated with the settlement ID and verify each transaction against its balance transaction details and reconcile if the total collect sum matches the total settlement amount received. *** ## Reconciling a Settlement Call the [Fetch Collects API](/api-reference/tazapay-api/fetch-collects) with the settlement ID to get the list of collects included in that settlement. ``` GET /v3/settlement/{id}/transactions/collect ``` Each entry in the response contains the collect `id` and its `balance_transaction_id`. You can get the settlement ID from [settlement webhooks](/api-reference/tazapay-api/settlement-webhooks) or the dashboard. From each [collect object](/api-reference/tazapay-api/collects), take the `balance_transaction_id` and call the [Fetch Balance Transaction API](/api-reference/tazapay-api/fetch-balance-transaction) to get the details of the net amount added to your balance and any associated FX. ``` GET /v3/balance_transaction/{id} ``` The balance transaction gives you the full breakdown for that collect: | Field | What it tells you | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `amount` / `currency` | The gross amount received, in the incoming currency. | | `fee_details` | Fees deducted from the gross amount. | | `fx_conversions` | Any [FX conversion](/collection-accounts/incoming-payments/fx) applied, with the exchange rate and the initial and final amounts. | | `net` | The net amount credited to your balance after fee deductions and FX conversions. | Sum the `net` amounts across all balance transactions in the settlement and check that the total matches the settlement amount received in your account. If the totals match, the settlement is fully reconciled. If they do not, compare each collect's `net` against your records to isolate the transaction causing the difference. Amounts are integers with 2 implied decimal places - divide by 100 to get the actual value (100000 is USD 1,000.00). See [Decimal Currencies](/api-reference/appendix/decimal-currencies). Also ensure you compare net amounts in the same currency - collects in a non-holding currency are converted to your primary holding currency before being credited. See [FX](/collection-accounts/incoming-payments/fx). *** ## See Also The settlement object and how settlements work. Tracking credits and debits across your balances. When currency conversion happens on incoming collects. Field-level reference for the collect object. # Reversals Source: https://developer.tazapay.com/collection-accounts/incoming-payments/reversals What happens when a collect fails — funds are returned to the source If a collect fails, either after a [hold](/collection-accounts/incoming-payments/holds) is rejected or due to another processing failure, Tazapay reverses the complete transaction amount back to the source. Reversal tracking details will be available directly on the collect object (coming soon). Until then, reach out to [support@tazapay.com](mailto:support@tazapay.com) if you need reversal tracking information for a specific collect. *** ## See Also How a collect reaches the failed state that triggers a reversal. The most common precursor to a reversal. # Collect Webhooks Source: https://developer.tazapay.com/collection-accounts/incoming-payments/webhooks Subscribe to webhook events to be notified of incoming collects in real time Tazapay sends emails and webhooks for events related to [collects](/api-reference/tazapay-api/collect-webhook). You can subscribe to these events by configuring a webhook endpoint from the [Tazapay Dashboard](https://dashboard.tazapay.com/). *** ## Common Collect Events | Event | When it fires | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `collect.succeeded` | The incoming payment was credited successfully to the collection account. | | `collect.failed` | The incoming payment could not be processed and has failed. | | `collect.on_hold` | The collect was placed on a compliance hold for review. See [Compliance Holds](/collection-accounts/incoming-payments/holds). | | `collect.detected` | (Wallets only) The blockchain transaction was detected before confirmation. | *** ## See Also Retrieve collect details programmatically. View collects in the Tazapay dashboard. # Introduction Source: https://developer.tazapay.com/collection-accounts/on-behalf-of/introduction Create collection accounts and receive funds on behalf of your customers **Managed Payments** lets platforms and fintechs embed Tazapay's money-movement infrastructure to move funds *for their customers* without building banking rails or reconciliation in-house. Tazapay's **On Behalf Of (OBO)** infrastructure lets you create collection accounts (virtual accounts or stablecoin wallets) and receive incoming funds on behalf of each of your customers, who can be individuals or businesses. Every incoming payment is automatically attributed to the right customer, so funds are always traceable and correctly reconciled. *** ## How the pieces fit together Your customers live in your **Platform / Fintech account**. Each customer is represented by a single, reusable [Entity object](/api-reference/tazapay-api/entity), so the same customer can be used across both collections and payouts. You never onboard a customer twice. Both flows settle into a single common [balance](/api-reference/tazapay-api/balance) held at the platform / fintech level. Collections **increase** the balance and payouts **reduce** it, so you always have one consolidated view of funds across all your customers. *** ## The end-to-end flow At a high level, collecting on behalf of a customer looks like this: *** ## Next What KYC is required, how approval works, and the reliance model for instant transactions. Reuse verification you've already done by passing Sumsub KYC tokens to Tazapay. # KYC provider tokens Source: https://developer.tazapay.com/collection-accounts/on-behalf-of/kyc-provider-tokens Reuse existing verification by passing Sumsub KYC tokens to Tazapay If you already verify your customers through a KYC provider, you don't have to collect the same information twice. Tazapay is integrated with [Sumsub](https://www.sumsub.com/) and can consume [KYC tokens](https://sumsub.com/reusable-kyc/), so the verification you've already completed can be reused when onboarding an entity. This is ideal for platforms running their own onboarding funnel, and it pairs naturally with the [reliance model](/collection-accounts/on-behalf-of/onboarding-and-required-information#the-reliance-model) for instant collections. *** ## How it works You verify the customer as part of your own onboarding, then pass the resulting **token** to Tazapay when creating the entity. Tazapay consumes the token to retrieve and validate the verification, with no need to re-upload documents. *** ## Why use provider tokens | No duplicate KYC | Faster onboarding | One source of truth | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Reuse verification you've already done, so your customers don't repeat the process. | Skip re-collecting documents and move straight to creating collection accounts. | Keep verification consistent between your platform and Tazapay. | *** ## Supported providers | Provider | Status | What Tazapay consumes | | ---------- | --------- | ---------------------- | | **Sumsub** | Supported | KYC verification token | Additional KYC providers may be supported over time. Contact [Tazapay Support](mailto:support@tazapay.com) in case you need Tazapay to add support for your KYC provider. *** ## Steps to integrate Complete KYC for your customer within your existing Sumsub flow. Retrieve the Sumsub verification token for the completed applicant. Provide the token when creating the entity via the [Create Entity API](/api-reference/tazapay-api/create-entity) in the `onboarding_package_url` field. Tazapay validates the verification with Sumsub and creates the entity with the reused KYC. *** ## What's next Review KYC requirements and the reliance model. Create virtual accounts and stablecoin wallets for your onboarded entities. # Onboarding Source: https://developer.tazapay.com/collection-accounts/on-behalf-of/onboarding-and-required-information KYC requirements, Approval timelines, and Reliance model Before you can create a collection account for a customer, that customer must be onboarded as an [Entity](api-reference/tazapay-api/entity) and pass KYC. This page covers what's required, how long approval takes, and how the reliance model lets you provision collection accounts instantly. *** ## Full KYC is mandatory Full KYC is mandatory for every entity, both individuals and businesses, before a collection account can be created on their behalf. This keeps incoming funds compliant, traceable, and correctly attributed. ### Related Links * [Onboarding requirements for businesses](managed-payments/onboarding-requirements/onboarding-requirements-businesses) * [Onboarding requirements for individuals](managed-payments/onboarding-requirements/onboarding-requirements-individuals) *** ## The standard flow In the standard flow, an entity must be **approved** before you can create a collection account for it. After you submit an entity for KYC, Tazapay reviews it. This typically takes a few hours. *** ## The simplified model If you're approved for the simplified model, you can create a collection account for an entity as soon as it is in **submitted** status, without waiting for Tazapay's approval. The simplified model is enabled after review. You will still have to submit the entire KYC pack of your customer. Contact your Tazapay representative to find out whether you qualify. *** ## Standard vs. simplified | | Standard flow | Simplified model | | --------------------------------------------------- | ----------------------------- | --------------------------------------------------- | | Entity status needed to create a collection account | approved | submitted | | When Tazapay reviews | In the flow (before approval) | After the collection account creation (post-review) | | Time to first collection | After review (\~ a few hours) | Instant | | Availability | Default for all platforms | On approval only | *** ## Entity lifecycle Both models share the same [entity object](/api-reference/tazapay-api/entity). The only difference is the status at which a collection account can be created. Create an Individual or Business entity for your customer via the [Create Entity API](/api-reference/tazapay-api/create-entity). Provide the required information and submit the entity via the [Submit Entity API](/api-reference/tazapay-api/submit-entity-business). The entity moves to **submitted**. **Standard:** wait for approved. **Simplified:** proceed at submitted. Issue a [virtual account](/collection-accounts/coverage/virtual-accounts) or [stablecoin wallet](/collection-accounts/coverage/stablecoins) for the entity. # Introduction Source: https://developer.tazapay.com/collection-accounts/overview/introduction Receive payments through local account numbers and stablecoin wallets, credited to your Tazapay balance Global Collection Accounts Global Collection Accounts let you receive payments through local account numbers in multiple markets, without setting up local entities or foreign bank accounts. Payers transfer funds in their own currency over local rails, SWIFT, or supported blockchains, and each payment is credited to your Tazapay balance which you can hold, convert, withdraw, or use for payouts. Every Tazapay account has access to two collection account types: Virtual Accounts for fiat and Stablecoin Wallets. ## Key Capabilities * **Local account numbers** - Payers transfer to a domestic account number over local rails (FAST, ACH, SEPA, Faster Payments) at local cost and speed. SWIFT is available for cross-border wires. * **Single multi-currency balance** - You can hold in the currencies you choose. Conversion is applied at the moment of credit, so there is no separate FX step. See [FX](/collection-accounts/incoming-payments/fx). * **Screening** - Every incoming payment is screened before it is credited. Payments that require review are placed on a [hold](/collection-accounts/incoming-payments/holds). * **Collections on behalf of** - You can provision dedicated accounts for each of your customers; every payment carries the customer's entity ID for attribution. See [Collections on Behalf Of](/collection-accounts/integration-guides/collections-on-behalf-of). *** ## Use Case Guides Collect from buyers in their currency, hold in yours. White label collection accounts inside your own product. A named account per seller — every payment attributed automatically. # Prerequisites Source: https://developer.tazapay.com/collection-accounts/overview/prerequisites What you need before you request Collection Accounts Collection Accounts (Virtual Accounts and Stablecoin Wallets) can be requested for your own business or on behalf of your customers. In both cases, the entity that will receive funds must be onboarded on Tazapay first. ## Request for your own business Complete business verification (KYB) and finish onboarding on Tazapay. Once your account is active, you can request Collection Accounts immediately. The information and documents you need to complete verification. ## Request on behalf of your customers Requesting on behalf of customers requires customer onboarding to be enabled on your account. Confirm it's enabled before you start: * **Dashboard** - an **Entities** section appears in your navigation. * **API** - you can create and retrieve the [entity object](/api-reference/tazapay-api/entity). If you don't see either, the capability isn't enabled yet. Contact [support@tazapay.com](mailto:support@tazapay.com) or your Tazapay point of contact to have it turned on. Once enabled, submit your customer's full entity details to Tazapay. We verify the entity, then provision Collection Accounts against it. How to submit complete entity details for your customers. **No approval step for eligible on-behalf-of flows.** In some configurations, submitting your customer's KYB details is the only requirement. Collection Accounts are allocated on submission, with no separate approval before provisioning. Your Tazapay point of contact will confirm whether your account is set up this way. Otherwise, provisioning time depends on your risk profile. Most Collection Accounts are created instantly. Some corridors require a manual review, which typically takes a few hours. # Quickstart Source: https://developer.tazapay.com/collection-accounts/overview/quickstart Create a collection account, receive a simulated payment, and see the funds credited to your balance - end to end on sandbox real time. Everything below runs on sandbox, so no real money moves. By the end of this guide you will have provisioned a Virtual Account via API, simulated an incoming bank transfer, received the `collect.succeeded` webhook, fetched the collect, and confirmed the credit on your balance. You need two things before starting: a [sandbox account](https://dashboard-sandbox.tazapay.com) with API keys ([Get Started with Tazapay](/getting-started/overview/get-started-with-tazapay)) and an entity. > There is no real onboarding needed on sandbox, you can [create an entity](/api-reference/tazapay-api/create-entity) and [simulate its approval](/api-reference/tazapay-api/simulate-entity-status-in-sandbox) directly. *This walkthrough uses a Singapore SGD Virtual Account. The identical flow applies to other currencies and stablecoin wallets.* ## The flow at a glance 1. **Provision the account** - `POST /v3/collection_account` 2. **Account enabled** - the enablement request succeeds and `collection_account.status` flips to `enabled` 3. **Fetch account details** - the collection\_account object contains the bank account details 4. **Payer transfers funds** - a normal domestic transfer, or SWIFT, or an on-chain send 5. **Collect created & screened** - Tazapay creates a collect and runs compliance screening 6. **Collect succeeds** - `collect.succeeded` fires 7. **Balance credited** - funds land in your Tazapay balance, converted if needed. Track using the [balance\_transaction](/api-reference/tazapay-api/fetch-balance-transaction) object. The Tazapay API uses HTTP Basic authentication: your `API_Key` is the username and your `API_Secret` is the password, joined with a colon, Base64-encoded, and sent as `Authorization: Basic `. See [Authentication](/api-reference/api-overview/authentication) for the full breakdown. All calls in this guide use the sandbox base URL. See [Endpoints and Environments](/api-reference/api-overview/endpoints-and-environments). ```bash Sandbox base URL theme={null} https://service-sandbox.tazapay.com ``` `curl -u` performs the Basic encoding for you, so the examples below stay copy-pasteable: ```bash Set your credentials theme={null} export TZP_KEY="your_api_key" export TZP_SECRET="your_api_secret" export TZP_BASE="https://service-sandbox.tazapay.com" ``` Before creating anything, ask the Metadata API what your account is actually allowed to provision. This returns the payment method types, currencies, rails, and transfer limits available to you. ```bash Request theme={null} curl -X GET "$TZP_BASE/v3/metadata/collection_account/virtual_account?country=SG¤cies=SGD" \ -u "$TZP_KEY:$TZP_SECRET" ``` ```json Response (trimmed) theme={null} { "capabilities": [ { "payment_method_type": "local_bank_transfer_sgd", "currencies": [ "SGD" ], "transfer_limit": { "minimum": { "amount": 100, "ccy": "SGD" }, "maximum": { "amount": 100000000, "ccy": "SGD" }, "currency": "SGD" }, "local": { "fund_transfer_networks": [ { "name": "FAST", "additional_information": "Near-instant, 24x7." }, { "name": "PayNow", "additional_information": "Near-instant, 24x7." }, { "name": "MEPS", "additional_information": "Same-day on business days." } ] }, "on_behalf_of": { "support": true, "additional_requirements": [ "entity_submission_required" ] }, "setup_time": "instant", "account_reenablement_supported": true } ] } ``` Sandbox availability may differ from production. In production, what you can provision depends on your onboarding profile — if a corridor you need is missing here, check [Virtual Account coverage](/collection-accounts/coverage/virtual-accounts) and talk to your account manager. ### Related Links * [Virtual Account Coverage and Features API](/api-reference/tazapay-api/virtual-account-metadata) * [Stablecoin Features](/api-reference/tazapay-api/wallet-metadata) > This is an optional step; you can skip it if you already know what you can provision. Create a Singapore SGD Virtual Account on the local rail. Only `type` and `payment_method_type` are required by the schema; `country` and `currencies` are additionally required for virtual accounts. ```bash Request theme={null} curl -X POST "$TZP_BASE/v3/collection_account" \ -u "$TZP_KEY:$TZP_SECRET" \ -H "Content-Type: application/json" \ -d '{ "type": "virtual_account", "payment_method_type": "local_bank_transfer_sgd", "country": "SG", "currencies": ["SGD"], "alias": "quickstart-account", "description": "Quickstart test account for SGD collections" }' ``` ```json Response theme={null} { "id": "cva_d2dgk0552psfuj1he0", "object": "collection_account", "type": "virtual_account", "payment_method_type": "local_bank_transfer_sgd", "country": "SG", "currencies": [ "SGD" ], "status": "disabled", "alias": "quickstart-account", "description": "Quickstart test account for SGD collections", "requests": [ { "id": "cvar_dbqlkip52psfuj1heju", "object": "collection_account_request", "collection_account_id": "cva_d2dgk0552psfuj1he0", "type": "enablement", "status": "processing", "requested_currencies": [ "SGD" ], "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:39:25.03501Z", "status_description": "Activation in progress." } ], "status_description": "", "metadata": {}, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:39:25.03501Z" } ``` Note the account is created with status `disabled` with an `enablement` request attached; it cannot receive funds just yet. The account's `status` is derived from the state of that request, not set directly. For the full request lifecycle and every state a request can pass through, see [Collection Account Status Flow](/collection-accounts/requesting-for-vas/api#collection-account-status-flow). Save the returned `id`, every step below uses it: ```bash theme={null} "cva_d2dgk0552psfuj1he0" ``` Subscribe to `collection_account.creation_succeeded`. It fires when the enablement request succeeds and the status flips to `enabled`. ```json collection_account.creation_succeeded (trimmed) theme={null} { "type": "collection_account.creation_succeeded", "id": "evt_crqinqs584jmicmfjbhg", "object": "event", "created_at": "2024-09-26T09:39:55.369534811Z", "data": { "id": "cva_d2dgk0552psfuj1he0", "object": "collection_account", "payment_method_type": "local_bank_transfer_sgd", "status": "enabled", "currencies": [ "SGD" ], "virtual_account": { "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "bank_name": "STANDARD BANK LIMITED", "bank_codes": { "swift_code": "SLSGO2XXX" } }, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:39:25.03501Z" } } ``` The same family of events reports the unhappy paths. `creation_requires_action`, `creation_under_approval_hold`, `creation_failed`, `creation_cancelled`. Handle at least `creation_failed` before going live. > Complete list of events: [Collection Account Webhooks](/api-reference/tazapay-api/collection-account-webhooks). On setting up and securing your endpoint, see the [Webhooks Guide](/api-reference/appendix/webhooks-guide) and [Webhook Authentication](/api-reference/appendix/webhook-authentication). Poll the collection\_account object periodically until `status` is `enabled`. ```bash Request theme={null} curl -X GET "$TZP_BASE/v3/collection_account/$CVA_ID" \ -u "$TZP_KEY:$TZP_SECRET" ``` Once enablement succeeds, the account looks like this — `status: enabled`, and the `enablement` request in `requests` now reads `succeeded`: ```json expandable Collection Account — enabled SGD virtual account theme={null} { "id": "cva_d2dgk0552psfuj1he0", "object": "collection_account", "type": "virtual_account", "payment_method_type": "local_bank_transfer_sgd", "country": "SG", "currencies": [ "SGD" ], "status": "enabled", "alias": "quickstart-account", "description": "This account is used for SGD collections", "virtual_account": { "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "iban": "", "bank_name": "STANDARD BANK LIMITED", "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore" }, "bank_codes": { "swift_code": "SLSGO2XXX" }, "account_reenablement_supported": true }, "requests": [ { "id": "req_cva001enablement", "object": "collection_account_request", "collection_account_id": "cva_d2dgk0552psfuj1he0", "type": "enablement", "status": "succeeded", "requested_currencies": [ "SGD" ], "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:39:30.03501Z", "status_description": "Account enabled successfully." } ], "status_description": "", "metadata": {}, "created_at": "2024-09-26T09:39:25.03501Z", "updated_at": "2024-09-26T09:41:43.349835Z" } ``` Field-level reference: [Collection Account object](/api-reference/tazapay-api/global-collection-account-object). Fetch the collection\_account object and read the `virtual_account` block. These are the coordinates your payer transfers to. ```bash Request theme={null} curl -X GET "$TZP_BASE/v3/collection_account/$CVA_ID" \ -u "$TZP_KEY:$TZP_SECRET" ``` ```json Virtual account details to share with your payer theme={null} { "id": "cva_d2dgk0552psfuj1he0", "object": "collection_account", "status": "enabled", "country": "SG", "currencies": [ "SGD" ], "payment_method_type": "local_bank_transfer_sgd", "virtual_account": { "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "iban": "", "bank_name": "STANDARD BANK LIMITED", "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore" }, "bank_codes": { "swift_code": "SLSGO2XXX" } } } ``` The keys present under `bank_codes` vary by country and rail — it may contain `swift_code`, `routing_code`, `sort_code`, `ach_routing_number`, `fedwire_routing_number`, `bsb_code`, or `bank_code`. Read them dynamically rather than assuming a fixed set. Full reference: [Collection Account object](/api-reference/tazapay-api/global-collection-account-object). In production, these are the details you display to your customer or print on your invoice. The payer then makes a transfer to this account. Sandbox includes a **Collect Simulation** feature so you can mimic an incoming payment without moving real money. Go to the [Sandbox dashboard](https://dashboard-sandbox.tazapay.com/) → **Virtual Accounts/Wallets** → **Simulate Collect**, pick the account you just created, and simulate the `succeeded` state. You can simulate every intermediate and terminal state, which is how you exercise the unhappy paths in your integration: | State flow | What it exercises | | ----------------------- | ------------------------------------------- | | `succeeded` | The happy path - funds settled successfully | | `on_hold` → `succeeded` | Held for review, then cleared and settled | | `on_hold` → `failed` | Held for review and rejected | | `failed` | Collect rejected outright | Stablecoin wallets add `detected` transitions, since on-chain payments are visible before final confirmation. The complete matrix for both fiat and crypto is on [Simulating Collects on Sandbox](/api-reference/tazapay-api/simulate-collects-on-sandbox). Simulated collects also create a real sandbox balance, which you can then use to fund and test payouts end to end. **The webhook.** As soon as the collect settles, `collect.succeeded` fires. This is the event your system should treat as the signal that money arrived — note `balance_transaction`, which ties the collect to the ledger entry on your balance. ```json expandable collect.succeeded theme={null} { "type": "collect.succeeded", "id": "evt_d30mfcg3obm733raoh7g", "object": "event", "created_at": "2025-09-10T11:57:38.761234462Z", "data": { "id": "col_d30mfargpkanp3hrmqhg", "object": "collect", "amount": 100000, "currency": "SGD", "status": "succeeded", "type": "local_bank_transfer_sgd", "payer_details": { "name": "John Doe", "payer_bank": { "account_number": "", "name": "", "address": null, "bank_codes": { "swift_code": "sdasd93e" } }, "reference_id": "", "additional_information": "" }, "destination": "cva_d2dgk0552psfuj1he0", "destination_details": { "type": "virtual_account", "virtual_account": { "id": "cva_d2dgk0552psfuj1he0", "object": "virtual_account", "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "bank_name": "STANDARD BANK LIMITED", "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore", "postal_code": "", "state": "" }, "bank_codes": { "swift_code": "SLSGO2XXX" }, "currencies": [ "SGD" ], "iban": "" } }, "holding_currency": "SGD", "balance_transaction": "btr_d30mfcjgpkanp3hrmql0", "on_behalf_of": "", "metadata": {}, "created_at": "2025-09-10T11:57:31.967513Z", "tracking_details": null } } ``` > All collect events and their payloads: [Collect Webhooks](/api-reference/tazapay-api/collect-webhook). **Fetch the collect.** Take the collect ID from the webhook and fetch it directly: ```bash Request theme={null} curl -X GET "$TZP_BASE/v3/collect/col_d30mfargpkanp3hrmqhg" \ -u "$TZP_KEY:$TZP_SECRET" ``` ```json expandable Collect — succeeded USD collect theme={null} { "status": "success", "message": "", "data": { "id": "col_d2fapsh76og2qj0ej5g", "object": "collect", "amount": 100000, "currency": "USD", "holding_currency": "USD", "status": "succeeded", "type": "wire_transfer", "destination": "cva_d2dgk0552psfuj1he0", "destination_details": { "type": "virtual_account", "virtual_account": { "id": "cva_d2dgk0552psfuj1he0", "object": "virtual_account", "account_holder_name": "OM Grand Limited", "account_number": "0109866363", "bank_name": "STANDARD BANK LIMITED", "bank_branch": "8 MARINA BOULEVARD, 27-01, MARINA BAY FINANCIAL CENTRE", "bank_address": { "address_line_1": "", "address_line_2": "", "city": "", "country": "Singapore", "postal_code": "", "state": "" }, "bank_codes": { "swift_code": "SLSGO2XXX" }, "currencies": [ "USD" ], "iban": "" } }, "payer_details": { "name": "CMC COMPANY", "payer_bank": { "account_number": "1112019837840", "name": "C Bank", "address": null, "bank_codes": { "swift_code": "AJUM7CHBKXXX" } }, "reference_id": "", "additional_information": "CM Payment for Order 56" }, "balance_transaction": "btr_u7ftrgipu69og2qj1j1pg", "on_behalf_of": "", "metadata": {}, "tracking_details": null, "created_at": "2025-08-15T03:43:46.980214Z" } } ``` Field-level reference: [Collect object](/api-reference/tazapay-api/collects). Amounts are in the currency's smallest unit - 100000 here is USD 1,000.00. The four fields to reconcile against are `status` (`succeeded`), `amount` and `currency` (what arrived), `destination` (which collection account received it), and `balance_transaction` (the ledger entry). **Confirm the balance.** Finally, check that the funds are on your balance: ```bash Request theme={null} curl -X GET "$TZP_BASE/v3/balance" \ -u "$TZP_KEY:$TZP_SECRET" ``` ```json Response (trimmed) theme={null} { "status": "success", "message": "", "data": { "available": [ { "amount": "100000", "currency": "SGD" } ], "object": "balance", "updated_at": "2024-08-20T06:18:11.475605Z" } } ``` Balance amounts are strings in the currency's smallest unit "100000" is SGD 1,000.00. If the incoming currency is not one of your holding currencies, it is converted automatically at the point of credit rather than as a separate step - see [FX](/collection-accounts/incoming-payments/fx). *** ## Going to production * **Handle compliance holds** — subscribe to `collect.on_hold` and surface held payments rather than treating silence as failure → [Compliance Holds](/collection-accounts/incoming-payments/holds) * **Understand the full collect state machine**, including the wallet-only `detected` state → [State Machine](/api-reference/tazapay-api/collect-state-machine) * **Plan for reversals** when a collect fails after funds have arrived → [Reversals](/collection-accounts/incoming-payments/reversals) * **Decide your holding currencies** and how FX should behave → [FX](/collection-accounts/incoming-payments/fx) and [Enabling Additional Balance Currencies](/getting-started/core-concepts/enabling-additional-balance-currencies) * **Review coverage** for the corridors you actually need → [Virtual Accounts](/collection-accounts/coverage/virtual-accounts) and [Stablecoins](/collection-accounts/coverage/stablecoins) * **Collecting for your customers?** Read [Collections on Behalf Of](/collection-accounts/integration-guides/collections-on-behalf-of) for entity-level attribution * **Read the use case guide** matching your business ([B2B Collections](/collection-accounts/use-case-guides/b2b-collections), [Financial Institutions](/collection-accounts/use-case-guides/financial-institutions), or [Marketplaces](/collection-accounts/use-case-guides/marketplaces)) *** Prefer no code? Provision the same account from the Tazapay dashboard. Every field, enum, and endpoint for collection accounts. # Requesting via API Source: https://developer.tazapay.com/collection-accounts/requesting-for-vas/api Create Collection Accounts (Virtual Accounts and Stablecoin Wallets) programmatically using the Tazapay API Before creating, make sure you meet the [prerequisites](/collection-accounts/prerequisites). *** ## High-level Flow Collection Account Creation Flow Related Link: [Entity Onboarding](/collection-accounts/on-behalf-of/onboarding-and-required-information) Call the [Collection Account Metadata API](/api-reference/tazapay-api/virtual-account-metadata) to discover: * Available payment method types for your account * Supported currencies and domicile countries * Transfer limits and other features > This is an optional step and can be skipped if you already have the capabilities and coverage. Call the [Collection Account Creation API](/api-reference/tazapay-api/create-collection-account) with your requirements (account type, country, currencies, and payment method type). If Tazapay can fulfill the requirements, a Collection Account object is created with status `disabled` and an initial `enablement` request. > Related Link: [Collection Account Status Flow](/collection-accounts/requesting-for-vas/api#collection-account-status-flow) Subscribe to [webhook events](/api-reference/tazapay-api/collection-account-webhooks) to receive real-time status updates as the enablement request progresses. Once the request succeeds, the account status changes to `enabled` and is ready to receive funds. *** ## Collection Account Status Flow Every Collection Account has a status - either `enabled` or `disabled`. This helps identify whether it can currently receive funds. The status is determined by the state of requests associated with the account. Each time you want to enable, disable, or re-enable an account, a request is created and goes through its own lifecycle. The account status updates automatically based on how that request progresses. There are two types of requests: | Request Type | What it does | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enablement | Activates the account so it can start receiving funds. Created automatically when the account is first set up. Also created when a previously disabled account is re-enabled. | | Disablement | Deactivates the account so it stops accepting incoming payments. | Each request moves through its own set of states — such as `processing`, `requires_action`, `approval_hold` — before reaching a terminal state (`succeeded`, `failed`, or `cancelled`). The account status at any point reflects the outcome of the most recent request.