{ "openapi": "3.0.2", "info": { "version": "1.0.6", "title": "EBANX Pay-in API Reference", "description": "The EBANX Pay-in API enables seamless and transparent checkout experiences,\nallowing merchants to accept payments from multiple countries without redirects.\nWith this approach, customers remain on your store’s frontend throughout the entire payment process,\ncreating a smoother and more consistent checkout experience.\n", "termsOfService": "https://www.ebanx.com/en/legal/merchants/terms-and-conditions-for-payment-processing-services/", "contact": { "email": "sales.engineering@ebanx.com", "url": "http://www.ebanx.com" }, "license": { "name": "Proprietary", "url": "https://www.ebanx.com/en/legal/merchants/terms-and-conditions-for-payment-processing-services/" } }, "servers": [ { "url": "https://api.ebanxpay.com", "description": "Production API Server" }, { "url": "https://sandbox.ebanxpay.com", "description": "Sandbox API Server" } ], "tags": [ { "name": "FX" }, { "name": "Tokenization" }, { "name": "Enrollment" }, { "name": "Merchant Tools" }, { "name": "Direct Payments" }, { "name": "Payment Page" }, { "name": "Cancel" }, { "name": "Refund" }, { "name": "Refund or Cancel" }, { "name": "Query" } ], "paths": { "/ws/direct": { "post": { "tags": [ "Direct Payments" ], "summary": "Create a payment", "description": "Create a payment using EBANX Direct, the Transparent Checkout solution for pay-in. Customers complete the payment entirely on the merchant's website — no redirect to EBANX.\n", "operationId": "direct", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/direct-request" } } }, "description": "Payment body object", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/direct-response" }, { "$ref": "#/components/schemas/apm-error-response" }, { "$ref": "#/components/schemas/card-error-response" } ] } } } } } } }, "/ws/query": { "post": { "tags": [ "Query" ], "summary": "Query a payment", "description": "\nThe query operation is a server-to-server HTTP POST used by the merchant website to query EBANX for information about a specific payment.\n", "operationId": "query", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/query-response" }, { "$ref": "#/components/schemas/query-error-response" } ] } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/query-request" } } }, "description": "Payment body object", "required": true } } }, "/ws/cancel": { "post": { "tags": [ "Cancel" ], "summary": "Cancel a payment", "description": "\nThe cancel operation is a server-to-server operation that cancels payments.\n\nYou can cancel one payment if, and only if, its status is open (OP) or pending (PE). It’s important to know that confirmed payments (CO) cannot be cancelled.\n", "operationId": "cancel", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/cancel-response" }, { "$ref": "#/components/schemas/cancel-error-response" } ] } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel-request" } } }, "description": "Payment body object", "required": true } } }, "/ws/refund": { "post": { "tags": [ "Refund" ], "summary": "Refund a payment", "description": "This is a server-to-server operation that handles payment refunds. There are two sub-operations: `request` and `cancel`. The `request` operation requests a refund. The `cancel` operation cancels a refund.\n", "operationId": "refund", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-response" }, "examples": { "OK": { "value": { "payment": { "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221", "country": "br", "merchant_payment_code": "9dwdwdw1e31c4c234", "order_number": null, "status": "CO", "status_date": "2018-04-19 20:57:07", "open_date": "2018-04-19 20:56:42", "confirm_date": "2018-04-19 20:57:07", "transfer_date": null, "amount_br": "100.38", "amount_ext": "100.00", "amount_iof": "0.38", "currency_rate": "1.0000", "currency_ext": "BRL", "due_date": "2018-04-22", "instalments": "1", "payment_type_code": "itau", "pre_approved": false, "capture_available": null, "refunds": [ { "id": "68682", "merchant_refund_code": null, "status": "RE", "request_date": "2018-04-19 21:00:06", "pending_date": null, "confirm_date": null, "cancel_date": null, "amount_ext": "100.00", "description": "Testing notifications" } ] }, "status": "SUCCESS" } } } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-request" } } }, "description": "Payment body object", "required": true }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X POST 'https://sandbox.ebanxpay.com/ws/refund' \\\n -d 'integration_key=your_test_integration_key' \\\n -d 'operation=request' \\\n -d 'merchant_refund_code=787653' \\\n -d 'hash={{hash_here}}' \\\n -d 'amount=100.00' \\\n -d 'description=Order did not arrive'\n" }, { "lang": "Curl", "label": "Curl with Bank Details", "source": "curl --location --request POST 'http://api.ebanxpay.com/ws/refund' \\\n -d 'integration_key=INTEGRATION_KEY' \\\n -d 'hash={{hash_here}}' \\\n -d 'operation=request' \\\n -d 'amount=1.00' \\\n -d 'description=Order did not arrive' \\\n -d 'merchant_refund_code=787653' \\\n -d 'refund_id=3784756' \\\n -d 'bank_info[bank_name]=260 Nu Pagamentos S.A.' \\\n -d 'bank_info[bank_branch]=0001' \\\n -d 'bank_info[bank_account]=11111111-2' \\\n -d 'bank_info[account_type]=C' \\\n -d 'bank_info[details]=1' \\\n -d 'bank_info[bank_account_holder_document]=85351346893' \\\n -d 'bank_info[bank_account_holder_name]=José Silva'\n" } ] } }, "/ws/refundOrCancel": { "post": { "tags": [ "Refund or Cancel" ], "summary": "Refund or Cancel", "description": "The refund or cancel operation is a server-to-server operation to cancel payments or create payments refunds.\n\nWhen the refundOrCancel operation is requested, the following will occur according to the payment status:\n\n- Open (OP) or Pending (PE) -- the payment will be cancelled (status changes to CA), and no refund will be made.\n- Confirmed (CO) -- it will be made a full refund of the payment to the customer.\n", "operationId": "refundOrCancel", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-or-cancel-response" }, "examples": { "OK": { "value": { "payment": { "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9", "merchant_payment_code": "1461416920319", "order_number": "146", "status": "CA", "status_date": "2014-11-26 17:34:11", "open_date": "2014-11-25 10:45:56", "confirm_date": null, "transfer_date": null, "amount_br": "204.45", "amount_ext": "87.00", "amount_iof": "0.00", "currency_rate": "2.3500", "currency_ext": "USD", "due_date": "2014-12-2", "instalments": "1", "payment_type_code": "boleto", "pre_approved": false, "capture_available": null }, "operation": "cancel", "status": "SUCCESS" } } } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-or-cancel-request" } } }, "description": "Payment body object", "required": true }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X POST 'https://sandbox.ebanxpay.com/ws/refundOrCancel' \\\n -d 'integration_key=your_test_integration_key' \\\n -d 'merchant_refund_code=787653' \\\n -d 'hash={{hash_here}}' \\\n -d 'description=Order did not arrive'\n" } ] } }, "/ws/updatecustomerbankinfo": { "post": { "tags": [ "Refund" ], "summary": "Resend bank info", "description": "The resend refund bank info is a server-to-server operation to update the bank info data in a existing refund.\n", "operationId": "updatecustomerbankinfo", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resend-bank-info-response" }, "examples": { "OK": { "value": { "payment": { "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221", "country": "br", "merchant_payment_code": "9dwdwdw1e31c4c234", "order_number": null, "status": "CO", "status_date": "2018-04-19 20:57:07", "open_date": "2018-04-19 20:56:42", "confirm_date": "2018-04-19 20:57:07", "transfer_date": null, "amount_br": "100.38", "amount_ext": "100.00", "amount_iof": "0.38", "currency_rate": "1.0000", "currency_ext": "BRL", "due_date": "2018-04-22", "instalments": "1", "payment_type_code": "itau", "pre_approved": false, "capture_available": null, "refunds": [ { "id": "68682", "merchant_refund_code": null, "status": "RE", "request_date": "2018-04-19 21:00:06", "pending_date": null, "confirm_date": null, "cancel_date": null, "amount_ext": "100.00", "description": "Testing notifications" } ] }, "operation": "updatecustomerbankinfo", "status": "SUCCESS" } } } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resend-bank-info-request" } } }, "description": "Payment body object", "required": true } } }, "/ws/capture": { "post": { "tags": [ "Direct Payments" ], "summary": "Capture a payment", "description": "Captures a pre-authorized credit card payment.\nOnly applicable when `auto_capture` is set to `false` in the Direct operation and the payment\nhas been pre-approved by the acquirer.\n\nThe payment is identified by either `hash` or `merchant_payment_code`.\nPartial captures are supported in specific countries and require merchant-level configuration.\n", "operationId": "capture", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/capture-response" }, { "$ref": "#/components/schemas/capture-error-response" } ] } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-request" } } }, "description": "Payment body object", "required": true } } }, "/ws/ewallet-availableEWallets": { "post": { "tags": [ "Merchant Tools" ], "summary": "Get available e-wallets", "description": "Retrieve the e-wallet payment type codes available for a given country.\nThe returned codes can be used as `payment_type_code` in the Direct API.\n", "operationId": "availableEWallets", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/available-ewallets-success-response" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/available-ewallets-error-response" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/available-ewallets-request" } } }, "description": "Available e-wallets request body", "required": true } } }, "/ws/request": { "post": { "tags": [ "Payment Page" ], "summary": "Payment page", "description": "\nThis method allows you to create a payment using EBANX Payment Page, where the customer is redirected to EBANX’s website to enter his data.\n", "operationId": "request", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/request-response" }, "examples": { "OK": { "value": { "status": "SUCCESS", "payment": { "hash": "5ae0b5d4f1883ed4b214c0277af29f1981443f59a26eef87", "country": "br", "merchant_payment_code": "d59cwwwb7166e7", "order_number": null, "status": "OP", "status_date": null, "open_date": "2018-04-25 17:07:31", "confirm_date": null, "transfer_date": null, "amount_br": 100.38, "amount_ext": 100, "amount_iof": 0.38, "currency_rate": 1, "currency_ext": "BRL", "due_date": "2018-04-28", "instalments": 1, "payment_type_code": "_all", "pre_approved": false, "capture_available": null, "redirect_url": "https://sandbox.ebanxpay.com/checkout/?hash=5ae0b5d4f1883ed4b214c0277af29f1981443f59a26eef87" } } } } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/request-body" } } }, "description": "Payment body object", "required": true }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X POST 'https://sandbox.ebanxpay.com/ws/request' \\\n-d 'integration_key=your_test_integration_key_here' \\\n-d 'name=José Silva' \\\n-d 'email=josesilva@example.com' \\\n-d 'currency_code=BRL' \\\n-d 'amount=100' \\\n-d 'merchant_payment_code=d59cb7166e7' \\\n-d 'order_number=order_66', \\\n-d 'payment_type_code=_all' \\\n-d 'user_value_1=user_value_1', \\\n-d 'user_value_2=user_value_2', \\\n-d 'user_value_3=user_value_3', \\\n-d 'user_value_4=user_value_4', \\\n-d 'user_value_5=user_value', \\\n-d 'notification_url=example.com/notification', \\\n-d 'bypass_boleto_screen': true, \\\n-d 'zipcode=61919-230', \\\n-d 'street_number=1040', \\\n-d 'city=Maracanau', \\\n-d 'state=CE', \\\n-d 'country=br', \\\n-d 'phone_number': 8522847035, \\\n-d 'due_date=2024-12-20', \\\n-d 'sub_acc_name=account_name', \\\n-d 'sub_acc_image_url=example.com/image.png', \\\n-d 'instalments=1'" } ] } }, "/ws/exchange": { "post": { "tags": [ "FX" ], "summary": "Get an FX rate", "description": "The exchange operation is a server-to-server HTTP POST used by the merchant website to query EBANX for the current exchange rate for a given currency pair.\n\nThe `currency_code` parameter specifies the source currency and `currency_base_code` specifies the target currency. If `currency_base_code` is omitted, it defaults to `BRL`.\n\nBoth currencies are validated: `currency_code` must be one of the FX Token allowed base currencies (USD, EUR, GBP, CCL), and `currency_base_code` must be an active FX Token target currency. If either currency fails validation, the request returns `BP-EX-2`.\n", "operationId": "exchange", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/exchange-response" }, { "$ref": "#/components/schemas/exchange-error-response" } ] } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/exchange-request" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/exchange-request" } } }, "description": "Exchange request body", "required": true } } }, "/ws/exchange/getCurrencyRates": { "post": { "tags": [ "FX" ], "summary": "Get multiple FX rates", "description": "The getCurrencyRates operation is a server-to-server HTTP POST used to query EBANX for current exchange rates for multiple currency pairs at once.\n\nIt accepts arrays of source and target currency codes and returns all valid combinations. Invalid pairs (same code and base_code, inactive currencies, or currencies not found) are silently excluded from the response.\n\nUnlike `/ws/exchange`, this endpoint does **not** perform currency validation against the FX Token allowed list — it only validates authentication. Currency pairs that cannot be resolved are simply omitted from the result array.\n\nIf `currency_base_codes` is omitted or all entries are empty, it defaults to `[\"BRL\"]`.\n", "operationId": "getCurrencyRates", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/get-currency-rates-response" }, { "$ref": "#/components/schemas/get-currency-rates-error-response" } ] } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-currency-rates-request" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/get-currency-rates-request" } } }, "description": "Request body with arrays of currency codes", "required": true } } }, "/ws/fxtoken/get": { "post": { "tags": [ "FX" ], "summary": "Get an FX token", "description": "Retrieves a fixed exchange rate token for a given currency pair.\nThe token locks the current exchange rate for use in subsequent payment operations\n(e.g., `/ws/direct`), ensuring the merchant and customer see the same rate throughout\nthe checkout flow.\n\nThis feature must be enabled for your merchant account.\n", "operationId": "getFXToken", "security": [ { "integration_key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/fxtoken-success-response" }, { "$ref": "#/components/schemas/fxtoken-error-response" } ] } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fxtoken-request" } } }, "description": "FX Token request body", "required": true } } }, "/ws/token": { "post": { "tags": [ "Tokenization" ], "summary": "Create a card token", "description": "Creates a token for a given credit card to be used for recurring payments. Tokens expire after 14 months of their last use. To verify the credit card authenticity, EBANX creates a temporary transaction that will not be captured.\n", "operationId": "token", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/token-request" } } }, "description": "Create a credit card token", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/token-success-response" }, { "$ref": "#/components/schemas/token-error-response" } ] } } } } } } }, "/ws/token/setCVV": { "post": { "tags": [ "Tokenization" ], "summary": "Set a token CVV", "description": "Temporarily associates a CVV with an existing token. This CVV will be used by the next request made with the associated token and then discarded.\n\nUseful for one-click payments where the merchant already has the customer's card information but cannot store the CVV.\n", "operationId": "setCVV", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/set-cvv-request" } } }, "description": "Set CVV on an existing token", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/set-cvv-success-response" }, { "$ref": "#/components/schemas/set-cvv-error-response" } ] } } } } } } }, "/ws/token/query": { "post": { "tags": [ "Tokenization" ], "summary": "Query a token", "description": "Retrieves information about an existing card token, including card details (BIN, last four digits, brand, expiration date).\n", "operationId": "tokenQuery", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/query-request-2" } } }, "description": "Query an existing card token", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/query-success-response" }, { "$ref": "#/components/schemas/query-error-response-2" } ] } } } } } } }, "/ws/token/delete": { "post": { "tags": [ "Tokenization" ], "summary": "Delete a token", "description": "Deletes the network token associated with a card token, if one exists.\n", "operationId": "tokenDelete", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/delete-request" } } }, "description": "Delete the network token associated with a card token", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/delete-success-response" }, { "$ref": "#/components/schemas/delete-failed-response" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/delete-error-response" } } } } } } }, "/ws/cardbin": { "post": { "tags": [ "Merchant Tools" ], "summary": "Get BIN list", "description": "The BIN List API returns a list of valid card BINs accepted by EBANX.\nMerchants can use this information to make correct routing decisions based on the customer's card BIN.\n\nThis API is designed to be called periodically (server-to-server HTTP POST) so that merchants can keep their BIN table updated.\n", "operationId": "cardbin", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/card-bin-request" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/card-bin-success-response" }, { "$ref": "#/components/schemas/card-bin-error-response" } ] } } } }, "404": { "description": "Country not found", "content": { "text/html": { "schema": { "type": "string", "example": "Country not found" } } } } } } }, "/ws/getBankList": { "post": { "tags": [ "Merchant Tools" ], "summary": "Get bank list", "description": "Queries EBANX for the list of banks available for processing payments in a specific country.\nUse this endpoint to populate a bank selection interface on your checkout, so customers can\nchoose their preferred bank for EFT or bank transfer payments.\n", "operationId": "getBankList", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-bank-list-request" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/get-bank-list-request" } } }, "description": "Request body with country and optional payment type filter.", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-bank-list-success-response" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-bank-list-error-response" } } } } } } }, "/ws/instalmentsPlan": { "post": { "tags": [ "Merchant Tools" ], "summary": "Installments plan", "description": "Retrieves the installments plan for a given amount and currency.\nThe installment values are calculated based on the negotiated fees\nbetween the merchant and EBANX.\n", "operationId": "instalmentsPlan", "security": [ { "integration_key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/instalments-plan-request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/instalments-plan-success-response" }, { "$ref": "#/components/schemas/instalments-plan-error-response" } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/instalments-plan-error-response" } } } } } } }, "/ws/userenrollment": { "post": { "tags": [ "Enrollment" ], "summary": "Create an enrollment", "description": "This method enables you to create an enrollment using EBANX's User Enrollment API.\nThe enrollment flow allows merchants to set up recurring payment agreements with customers\nfor various payment methods across different countries.\n", "operationId": "userEnrollment", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-enrollment-request" } } }, "description": "User Enrollment request body", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/user-enrollment-response" }, { "$ref": "#/components/schemas/user-enrollment-error-response" } ] } } } } } } }, "/ws/userenrollment/cancel": { "post": { "tags": [ "Enrollment" ], "summary": "Cancel an enrollment", "description": "Cancels an existing enrollment identified by its `merchant_enrollment_code`.\n\nAlthough the canonical URL for this operation is `POST /ws/userenrollment`, it is\ndocumented as a separate path to clearly present its distinct request and response\ncontracts. The body must include `operation=cancel`.\n", "operationId": "userEnrollmentCancel", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel-request-2" } } }, "description": "Cancel enrollment request body", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/cancel-enrollment-response" }, { "$ref": "#/components/schemas/user-enrollment-error-response" } ] } } } } } } }, "/ws/userenrollment/update-subscription": { "post": { "tags": [ "Enrollment" ], "summary": "Update a subscription", "description": "Updates the mutable fields of an existing enrollment's subscription. Only `min_amount`,\n`max_amount`, `expiration_date` and `fixed_amount` are updatable; at least one must be\nprovided.\n\nAlthough the canonical URL for this operation is `POST /ws/userenrollment`, it is\ndocumented as a separate path to clearly present its distinct request and response\ncontracts. The body must include `operation=update_subscription`.\n", "operationId": "userEnrollmentUpdateSubscription", "security": [ { "integration_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-subscription-request" } } }, "description": "Update subscription request body", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/update-subscription-response" }, { "$ref": "#/components/schemas/update-subscription-error-response" }, { "$ref": "#/components/schemas/user-enrollment-error-response" } ] } } } } } } }, "/ws/documentbalance": { "get": { "tags": [ "Merchant Tools" ], "summary": "Get document balance", "description": "A server-to-server HTTP GET used by the merchant to check a customer's spending balance.\n\nAccording to local regulations, customers may have spending limits on international transactions.\nThis operation retrieves the amount the customer has already spent and the amount still available\nwithin the current month.\n", "operationId": "documentBalance", "security": [ { "integration_key": [] } ], "parameters": [ { "name": "document", "in": "query", "required": true, "description": "The customer's document number. For Brazil, this is a CPF (11 digits) or CNPJ (14 digits).\nNon-numeric characters are stripped automatically before validation.\n", "schema": { "type": "string", "minLength": 11, "maxLength": 18, "example": "85351346893" } }, { "name": "currency_code", "in": "query", "description": "The ISO 4217 three-letter currency code in which the balance values should be returned.\nDefaults to `USD` if not provided.\n", "schema": { "type": "string", "default": "USD", "enum": [ "BRL", "CLP", "COP", "EUR", "GBP", "MXN", "PEN", "USD" ], "example": "USD" } }, { "name": "country", "in": "query", "description": "The two-letter country code for the customer's document origin.\nDefaults to `br` if not provided.\n", "schema": { "type": "string", "default": "br", "enum": [ "br", "cl", "co", "mx", "pe" ], "example": "br" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/document-balance-response" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/document-balance-error-response" } } } } } } }, "/ws/zipcode": { "post": { "tags": [ "Merchant Tools" ], "summary": "Zip code", "description": "Query EBANX for the address associated with a given Brazilian zip code (CEP).\n\n**Only available for Brazil.**\n", "operationId": "zipCode", "security": [ { "integration_key": [] } ], "requestBody": { "description": "Zip code request body.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zip-code-request" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/zip-code-request" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zip-code-response" } } } }, "default": { "description": "Looking for errors response? Please visit this link: [API Error Codes page](https://docs.ebanx.com/docs/resources/error-codes/api-error-codes/)" } } } } }, "components": { "securitySchemes": { "integration_key": { "type": "apiKey", "in": "query", "name": "integration_key" } }, "schemas": { "browser-info": { "x-schema-group": "Shared", "type": "object", "title": "Browser Info", "x-conditional": "Required when `threeds_mode` is `data_only` or `data_only_preferred`", "description": "Browser information for 3D Secure data-only authentication modes.\n", "required": [ "ip_address", "accept_header", "user_agent", "language", "color_depth", "screen_height", "screen_width", "timezone_offset", "javascript_enabled", "java_enabled" ], "properties": { "ip_address": { "type": "string", "description": "The IP address of the customer's browser.\n", "example": "192.168.1.1" }, "accept_header": { "type": "string", "description": "The Accept header from the customer's browser HTTP request.\n", "example": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" }, "user_agent": { "type": "string", "description": "The User-Agent header from the customer's browser.\n", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" }, "language": { "type": "string", "description": "The browser language preference.\n", "example": "en-US" }, "color_depth": { "type": "string", "description": "The bit depth of the color palette for displaying images (in bits per pixel).\n", "example": "24" }, "screen_height": { "type": "string", "description": "The total height of the customer's screen in pixels.\n", "example": "1080" }, "screen_width": { "type": "string", "description": "The total width of the customer's screen in pixels.\n", "example": "1920" }, "timezone_offset": { "type": "string", "description": "The time-zone offset in minutes between UTC and the customer's browser local time.\n", "example": "-180" }, "javascript_enabled": { "type": "boolean", "description": "Whether JavaScript is enabled in the customer's browser.\n", "example": true }, "java_enabled": { "type": "boolean", "description": "Whether Java is enabled in the customer's browser.\n", "example": false } } }, "date-dmy": { "x-hidden": true, "title": "Date", "type": "string", "pattern": "^(0[1-9]|[1-2][0-9]|3[0-1])/(0[1-9]|1[0-2])/\\d{4}$", "description": "Date." }, "sub-account": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Sub Account Request", "description": "The sub account details. Required for payments using the sub account feature.\n", "properties": { "name": { "type": "string", "description": "Name of the sub account.\n", "maxLength": 32, "example": "My Store" }, "image_url": { "type": "string", "description": "URL of the logo of the sub account. Must be an HTTPS URL.\n", "maxLength": 200, "example": "https://example.com/logo.png" }, "code": { "type": "string", "description": "Sub account code. Used to identify a pre-registered sub account.\n", "example": "sub-acc-001" }, "legal_name": { "type": "string", "example": "ACME Comercio LTDA", "nullable": true, "description": "Legal name of the sub account entity.\n" }, "trade_name": { "type": "string", "example": "ACME", "nullable": true, "description": "Trade/commercial name of the sub account.\n" }, "account_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/account/a1b2c3", "nullable": true, "description": "URL of the sub account.\n" }, "account_country": { "type": "string", "example": "br", "nullable": true, "description": "Country of the sub account.\n" } } }, "payment-request-base": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Payment Request Base", "description": "Base fields shared across all payment requests.\n", "required": [ "amount_total", "country", "payment_type_code", "currency_code" ], "properties": { "name": { "type": "string", "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer name.\n", "maxLength": 100, "example": "José Silva" }, "email": { "type": "string", "nullable": true, "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer email address. Must be a valid email.\n", "format": "email", "maxLength": 100, "example": "jose@example.com" }, "phone_number": { "type": "string", "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer phone number.\n", "maxLength": 30, "example": "+5531977777777" }, "merchant_payment_code": { "type": "string", "nullable": true, "description": "The payment hash Merchant Payment Code (unique merchant ID).\n", "maxLength": 40, "example": "merchant-payment-code-0001" }, "amount_total": { "type": "number", "description": "The amount in the specified currency (`currency_code`). Must not contain commas.\n", "example": 99.85, "minimum": 0 }, "country": { "type": "string", "example": "br", "description": "The two-letter country code for the customer country.\n", "minLength": 2, "maxLength": 2, "default": "br" }, "payment_type_code": { "type": "string", "description": "The code of the payment method.\n", "example": "creditcard" }, "currency_code": { "type": "string", "description": "The source currency code (ISO 4217 three-letter code).\n", "minLength": 3, "maxLength": 3, "example": "BRL" }, "document": { "type": "string", "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer's national identification number (e.g., CPF/CNPJ for Brazil, RUT for Chile, CI for Uruguay).\n", "maxLength": 32, "example": "853.513.468-93" }, "birth_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer's birth date.\n", "example": "15/03/1990" }, "address": { "type": "string", "nullable": true, "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer address (street name).\n", "minLength": 1, "maxLength": 100, "example": "Rua E" }, "city": { "type": "string", "nullable": true, "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer city.\n", "minLength": 1, "maxLength": 80, "example": "Maracanau" }, "state": { "type": "string", "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer state/region/province.\n", "maxLength": 40, "example": "SP" }, "zipcode": { "type": "string", "x-conditional": "Required unless configured as optional by merchant agreement", "description": "Customer's zipcode.\n", "maxLength": 20, "example": "61919-230" }, "due_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "x-conditional": "Required for boleto and cash payment types. Optional for card payments.", "description": "Expiry date of the payment.\n", "example": "31/12/2027" }, "instalments": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 48 }, { "type": "string", "pattern": "^\\d+-\\d+$" } ], "x-conditional": "Applicable only for credit card payments. Maximum value depends on country and merchant contract.", "description": "The number of instalments of the amount.\nAccepts a single integer (e.g. `3`) or a range string (e.g. `\"1-5\"`).\nMaximum depends on country and merchant contract.\n", "default": 1, "example": 1 }, "device_id": { "type": "string", "example": "5a7b9c1d2e3f", "description": "Unique ID to identify the customer's device.\nUsed for anti-fraud purposes.\n", "maxLength": 200 }, "notification_url": { "type": "string", "description": "URL to send notifications for this payment.\nOverrides the merchant's default notification URL.\n", "maxLength": 2000, "example": "https://merchant.com/notifications" }, "redirect_url": { "description": "The URL to redirect the customer after the payment. Overrides the merchant's default redirect URL.\nAccepts either a single URL string or an object with `success`, `failure`, and `cart` URLs for result-based redirection.\n", "example": "https://merchant.com/checkout/complete", "oneOf": [ { "type": "string", "maxLength": 2000 }, { "type": "object", "title": "Result-Based Redirect URLs", "properties": { "success": { "type": "string", "description": "URL to redirect on successful payment.", "example": "https://merchant.example.com/success" }, "failure": { "type": "string", "description": "URL to redirect on failed payment.", "example": "https://merchant.example.com/failure" }, "cart": { "type": "string", "description": "URL to redirect back to cart.", "example": "https://merchant.example.com/cart" } } } ] }, "sub_account": { "$ref": "#/components/schemas/sub-account" }, "eft_code": { "type": "string", "example": "bancolombia", "nullable": true, "description": "Bank code for EFT (Electronic Funds Transfer) payments.\n" }, "expiration_time_in_seconds": { "type": "integer", "example": 3600, "description": "Expiration time for the payment in seconds.\n" }, "fx_token": { "type": "string", "example": "fx_a1b2c3d4", "description": "Token for locking an exchange rate.\n" } } }, "ar-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Argentina Request Base", "properties": { "document": { "description": "Customer's CUIT, CUIL, or DNI number.\n", "type": "string", "example": "30-52135353-1" }, "country": { "type": "string", "example": "ar", "enum": [ "ar" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "ARS", "USD" ] }, "address": { "type": "string", "example": "Calle Florida 100" }, "zipcode": { "type": "string", "example": "1005" }, "city": { "type": "string", "example": "Buenos Aires" }, "state": { "type": "string", "example": "CABA" }, "phone_number": { "type": "string", "example": "+5411912345678" } } }, "threeds-mode": { "title": "3DS Mode", "x-schema-group": "3DS", "type": "string", "description": "3D Secure authentication mode for card payments. Determines how the authentication flow is executed.\n", "oneOf": [ { "enum": [ "data_only" ], "description": "Data-only (frictionless) authentication. Only device and browser data is sent to the issuer for risk assessment — no cardholder interaction." }, { "enum": [ "data_only_preferred" ], "description": "Preferred data-only mode. Attempts frictionless authentication first; falls back to full challenge if the issuer requires it." }, { "enum": [ "full_authentication" ], "description": "Full 3DS authentication with challenge. The cardholder is redirected to the issuer's authentication page within the EBANX flow." }, { "enum": [ "redirect_data_only" ], "description": "Data-only authentication with redirect. Collects device/browser data and redirects externally, but no interactive challenge is presented." }, { "enum": [ "redirect_full_authentication" ], "description": "Full 3DS authentication with redirect. The cardholder is redirected to an external URL to complete the challenge." } ], "example": "data_only" }, "card-request": { "x-schema-group": "Shared", "type": "object", "title": "Card Request", "description": "Card payment details.\nWhen using a token for recurring/stored payments, only `token` is required instead of `card_number`, `card_name`, `card_due_date`, and `card_cvv`.\n", "properties": { "card_number": { "type": "string", "x-conditional": "Required for non-tokenized payments", "description": "Card number.\n", "example": "4111111111111111", "minLength": 12, "maxLength": 19 }, "card_name": { "type": "string", "x-conditional": "Required for non-tokenized payments", "description": "Cardholder name.\n", "example": "José Silva", "maxLength": 50 }, "card_due_date": { "type": "string", "x-conditional": "Required for non-tokenized payments", "description": "Card expiration date (\"valid thru\"). Accepts formats: m/yyyy (6-7 chars) or m/yy (4-5 chars).\nTwo-digit years are automatically expanded (e.g., 9/25 becomes 9/2025).\n", "example": "12/2030", "minLength": 4, "maxLength": 7 }, "card_cvv": { "type": "string", "nullable": true, "x-conditional": "Required when card_cvv_mode is 'provided' or not set. Not required when card_cvv_mode is 'recurrent'", "description": "Card security code (CVV/CVC).\n", "example": "123", "minLength": 3, "maxLength": 4 }, "card_pin": { "type": "string", "example": "1234", "nullable": true, "description": "Card PIN for markets that require PIN-based authentication (e.g., Nigeria, India).\n", "minLength": 4, "maxLength": 6 }, "auto_capture": { "type": "boolean", "nullable": true, "description": "If true, the payment will be captured automatically by EBANX; if false, the payment will have to be captured by the merchant using the capture endpoint.\n", "default": true, "example": true }, "card_cvv_mode": { "type": "string", "description": "Defines how the CVV is handled. Defaults to `provided` if not set.\nAn empty string is treated as the default (provided).\n", "enum": [ "", "provided", "recurrent" ], "default": "provided", "example": "provided" }, "soft_descriptor": { "type": "string", "example": "EBANX *STORE", "nullable": true, "description": "Custom billing descriptor text displayed on the cardholder's statement.\n", "maxLength": 22 }, "customer_tokenization_consent": { "type": "boolean", "example": true, "nullable": true, "description": "Whether the customer has consented to card tokenization for future payments.\n" }, "google_pay": { "nullable": true, "description": "Google Pay token data for payments authenticated via Google Pay.\nMay be a JSON object or a JSON-encoded string.\n" }, "network_token_pan": { "type": "string", "example": "4111111111111111", "nullable": true, "description": "Network token PAN replacing the actual card number.\n" }, "network_token_expire_date": { "type": "string", "nullable": true, "description": "Expiration date of the network token, in the card \"valid thru\" format (m/yyyy or m/yy).\n", "example": "12/2030" }, "network_token_cryptogram": { "type": "string", "example": "AJkBESVKAAAAAAAAAAAAAAAAAAA=", "nullable": true, "description": "Cryptogram for network token authentication.\n" }, "network_token_eci": { "type": "string", "example": "05", "nullable": true, "description": "Electronic Commerce Indicator for the network token transaction.\n" }, "network_token_raw_bin": { "type": "string", "example": "411111", "nullable": true, "description": "Raw BIN (Bank Identification Number) from the network token.\n" }, "network_token_raw_last4": { "type": "string", "example": "1234", "nullable": true, "description": "Last 4 digits from the network token.\n" }, "network_token_wallet_type": { "type": "string", "example": "google_pay", "nullable": true, "description": "Wallet type associated with the network token (e.g., google_pay, apple_pay).\n" }, "using_network_token": { "type": "boolean", "example": true, "nullable": true, "description": "Indicates whether this transaction uses a network token instead of actual card credentials.\n" }, "token": { "type": "string", "example": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6", "nullable": true, "description": "EBANX card token for recurring or stored card payments.\nWhen provided, card details (`card_number`, `card_name`, `card_due_date`, `card_cvv`) are not required.\n", "minLength": 32, "maxLength": 128 }, "threeds_mode": { "description": "3D Secure authentication mode.\n", "allOf": [ { "$ref": "#/components/schemas/threeds-mode" } ] }, "threeds_redirect_url": { "type": "string", "x-conditional": "Required when `threeds_mode` is `redirect_full_authentication` or `redirect_data_only`", "description": "The URL where the cardholder is redirected after completing 3DS authentication.\n", "example": "https://www.merchant.com/3ds-response" }, "threeds_eci": { "type": "string", "description": "Electronic Commerce Indicator from an external 3DS authentication.\nUsed when the merchant performs 3DS authentication outside of EBANX.\n", "example": "05" }, "threeds_cryptogram": { "type": "string", "description": "Cryptogram (CAVV) from an external 3DS authentication.\n", "example": "AAIBAkl0NwmHglFBAXQ3AAAAAAA" }, "threeds_xid": { "type": "string", "description": "Transaction ID (XID) from an external 3DS authentication.\n", "example": "AAIBAkl0NwmHglFBAXQ3AAAAAAA" }, "threeds_version": { "type": "string", "description": "3DS protocol version from an external 3DS authentication.\n", "example": "2" }, "threeds_force": { "type": "boolean", "example": false, "nullable": true, "description": "Force 3DS authentication even when not required by the acquirer.\n" }, "threeds_data_only": { "type": "boolean", "example": false, "nullable": true, "description": "Perform data-only 3DS authentication without full cardholder challenge.\n" }, "threeds_trxid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "Directory Server Transaction ID from an external 3DS authentication.\n" } } }, "transaction-reference": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Transaction Reference Request", "description": "A transaction reference supplied with a card payment.\n", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The reference type. `arn` is an acquirer reference number and `tlid` is a\ntransaction link identifier.\n", "enum": [ "arn", "tlid" ], "example": "tlid" }, "value": { "type": "string", "description": "The reference value. For `arn`, this is a non-empty string of up to 255\ncharacters. For `tlid`, this is exactly 22 characters matching\n`[A-Za-z0-9-_]`.\n", "minLength": 1, "maxLength": 255, "example": "AbCdEfGhIjKlMnOpQrStUv" } } }, "cof-type": { "title": "COF Type", "x-schema-group": "Card on File", "type": "string", "description": "Indicates whether this is the initial or a subsequent (stored) card-on-file transaction.\n", "oneOf": [ { "enum": [ "INITIAL" ], "description": "First-time card storage. The customer explicitly authorizes the merchant to store their card credentials." }, { "enum": [ "STORED" ], "description": "Subsequent transaction using previously stored card credentials." } ], "example": "INITIAL" }, "cof-initiator": { "title": "COF Initiator", "x-schema-group": "Card on File", "type": "string", "description": "Indicates who initiated the card-on-file transaction.\n", "oneOf": [ { "enum": [ "CIT" ], "description": "Customer-initiated transaction. The cardholder is actively participating in the transaction." }, { "enum": [ "MIT" ], "description": "Merchant-initiated transaction. The merchant initiates the charge without the cardholder being present." } ], "example": "CIT" }, "cof-trans-type": { "title": "COF Transaction Type", "x-schema-group": "Card on File", "type": "string", "description": "The type of card-on-file transaction being performed.\n", "oneOf": [ { "enum": [ "CUSTOMER_COF" ], "description": "A customer-initiated transaction using stored card credentials (e.g., one-click purchase)." }, { "enum": [ "INSTALLMENT" ], "description": "A series of charges for a single purchase, split into multiple payments." }, { "enum": [ "MERCHANT_COF" ], "description": "A merchant-initiated transaction using stored card credentials for a specific service (e.g., no-show fee)." }, { "enum": [ "SCHEDULED_RECURRING" ], "description": "A recurring charge at regular, predictable intervals (e.g., monthly subscription)." }, { "enum": [ "UNSCHEDULED_RECURRING" ], "description": "A charge at irregular intervals, triggered by a specific event (e.g., account top-up when balance is low)." } ], "example": "CUSTOMER_COF" }, "cof-info-request": { "x-schema-group": "Shared", "type": "object", "title": "Card on File Info Request", "description": "Card-on-File (COF) transaction details.\nRequired for merchants using stored card functionality.\n", "required": [ "cof_type", "initiator", "trans_type" ], "properties": { "cof_type": { "oneOf": [ { "$ref": "#/components/schemas/cof-type" } ], "description": "Indicates whether this is the initial or a subsequent (stored) card-on-file transaction.\n" }, "initiator": { "oneOf": [ { "$ref": "#/components/schemas/cof-initiator" } ], "description": "Indicates who initiated the transaction.\n" }, "trans_type": { "oneOf": [ { "$ref": "#/components/schemas/cof-trans-type" } ], "description": "The type of card-on-file transaction.\n" }, "initiated_by": { "type": "string", "example": "merchant", "nullable": true, "description": "Indicates whether the transaction was initiated by the merchant or the cardholder.\n" }, "mandate_id": { "type": "string", "nullable": true, "x-conditional": "Required when `cof_type` is `STORED`", "description": "Links the transaction with a previous agreement that allows the merchant\nto charge the customer repeatedly. Format varies by card brand.\n", "example": "MCCABC1XY0101" } } }, "card-payment-features": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Card Payment Features", "properties": { "card": { "x-conditional": "Required when paying with full card details. Not required when using a token for recurring/stored card payments.", "$ref": "#/components/schemas/card-request" }, "create_token": { "type": "boolean", "nullable": true, "description": "If true, generates a card `token` for future recurring or stored card payments.\n", "example": false }, "token": { "type": "string", "nullable": true, "description": "An existing EBANX card `token` for recurring billing.\nTokens expire after 14 months of last use.\n", "minLength": 32, "maxLength": 128, "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "transaction_references": { "type": "array", "description": "Transaction references supplied with a card payment.\n", "items": { "$ref": "#/components/schemas/transaction-reference" } }, "cof_info": { "$ref": "#/components/schemas/cof-info-request" } } }, "card": { "x-schema-group": "Requests", "title": "Argentina Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "cabal", "creditcard", "debitcard", "diners", "mastercard", "naranja", "visa" ] } } } ] }, "bank-details": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Bank Details", "description": "Bank account details for the payment.\n", "properties": { "bank_code": { "type": "string", "description": "The bank code.\n", "example": "001" }, "bank_name": { "type": "string", "description": "The bank name.\n", "example": "Banco de Bogotá" }, "bank_branch": { "type": "string", "description": "The bank branch number.\n", "example": "1234" }, "bank_account": { "type": "string", "description": "The bank account number.\n", "example": "123456789" }, "bank_account_type": { "type": "string", "description": "The type of bank account.\n", "example": "C" }, "account_number": { "type": "string", "description": "Customer's bank account number (CBU/CVU).\n", "example": "0000003100010000000001" } } }, "banktransfer": { "x-schema-group": "Requests", "title": "Argentina Bank Transfer Payment Request", "description": "Bank transfer payment request for Argentina.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "type": "object", "title": "Banktransfer Extra Fields", "properties": { "payment_type_code": { "description": "Value must be banktransfer for Bank Transfer payments.", "type": "string", "example": "banktransfer", "enum": [ "banktransfer" ] }, "bank_details": { "$ref": "#/components/schemas/bank-details" } } } ] }, "cupon": { "x-schema-group": "Requests", "title": "Argentina Cupon de Pagos Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "type": "object", "title": "Cupon Extra Fields", "properties": { "document": { "type": "string", "example": "23876543214" }, "payment_type_code": { "description": "The value must be cupon for Cupon de Pagos payments.", "type": "string", "example": "cupon", "enum": [ "cupon" ] }, "currency_code": { "type": "string", "example": "ARS" } } } ] }, "debin": { "x-schema-group": "Requests", "title": "Argentina DEBIN Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "type": "object", "title": "DEBIN Extra Fields", "required": [ "bank_details" ], "properties": { "document_type": { "type": "string", "description": "Customer's document type (Argentina).\n- **CUIT** - Tax identification\n- **CUIL** - Labor identification\n- **DNI** - National identity document\n", "enum": [ "CUIL", "CUIT", "DNI" ], "example": "CUIT" }, "bank_details": { "$ref": "#/components/schemas/bank-details" }, "installments_plan_token": { "type": "string", "example": "iplan_a1b2c3", "description": "Token for a pre-approved installments plan.\n" }, "payment_type_code": { "description": "The value must be \"debin\" for DEBIN payments.", "type": "string", "example": "debin", "enum": [ "debin" ] }, "currency_code": { "description": "Currency code for DEBIN.\n", "enum": [ "ARS" ] } } } ] }, "mercadopago-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Mercado Pago Request Base", "description": "Base schema for Mercado Pago payment requests. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\nCustomers are redirected to the Mercado Pago checkout page to complete payment.\nSupports both wallet (`mercadopago`) and credit (`mpcredito`) payment types.\n", "properties": { "payment_type_code": { "type": "string", "description": "Set to **mercadopago** for wallet payments or **mpcredito** for Mercado Pago credit.", "enum": [ "mercadopago", "mpcredito" ], "example": "mercadopago" }, "redirect_url": { "type": "string", "description": "URL to redirect the customer back to after completing the payment\non the Mercado Pago checkout page.\n", "example": "https://merchant.example.com/callback", "maxLength": 2000 } } }, "mercadopago": { "x-schema-group": "Requests", "title": "Argentina Mercado Pago Wallet Payment Request", "description": "Mercado Pago Wallet payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "$ref": "#/components/schemas/mercadopago-request-base" } ] }, "enrollment-reference-fields": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Reference Fields", "description": "Fields used to reference/identify an enrollment, shared between ws/direct (enrollment+charge)\nand ws/userenrollment (standalone enrollment).\n", "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant's unique enrollment code.", "maxLength": 250, "example": "my-enrollment-code-123" }, "phone_number": { "type": "string", "description": "Customer's phone number.", "example": "5555555555" }, "identification": { "type": "string", "description": "Customer's identification number (alternative to document).", "example": "12345678901" }, "identification_type": { "type": "string", "description": "Type of the identification (e.g. cpf).", "example": "cpf" }, "notification_url": { "type": "string", "description": "URL EBANX calls to notify enrollment status changes.", "example": "https://merchant.example.com/notify" } } }, "back-urls": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Back URLs", "description": "Callback URLs the customer is redirected to after completing or failing the enrollment flow.\nShared between ws/direct (enrollment+charge) and ws/userenrollment (standalone enrollment).\nThe `required` constraint is context-dependent: ws/userenrollment requires both URLs, while\nws/direct accepts them as optional.\n", "properties": { "success": { "type": "string", "description": "URL to redirect the customer to on success.", "example": "https://merchant.example.com/success" }, "failure": { "type": "string", "description": "URL to redirect the customer to on failure.", "example": "https://merchant.example.com/failure" } } }, "direct-enrollment": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Base", "description": "Base enrollment object for recurring payment charge execution via /ws/direct.\nUsed to reference an existing customer enrollment by its merchant-provided code.\nThe enrollment creation (with full customer details) is done via /ws/userenrollment endpoints.\nFor /ws/direct, only the enrollment reference fields are needed.\n", "allOf": [ { "$ref": "#/components/schemas/enrollment-reference-fields" }, { "type": "object", "title": "Direct Enrollment Extra Fields", "properties": { "back_urls": { "$ref": "#/components/schemas/back-urls" } } } ] }, "enrollment-contact-fields": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Contact Fields", "description": "Contact data fields provided when creating an enrollment (country and email), shared between\nws/direct (enrollment+charge) and ws/userenrollment (standalone enrollment).\n", "properties": { "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2).", "minLength": 2, "maxLength": 2, "example": "br" }, "email": { "type": "string", "format": "email", "description": "Customer's email address.", "example": "john.doe@example.com" } } }, "enrollment-identity-fields": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Identity Fields", "description": "Customer identity fields (name and document) used when creating an enrollment for payment\ntypes that require them (e.g. Pix Automatico, MP Connect). Shared\nbetween ws/direct (enrollment+charge) and ws/userenrollment (standalone enrollment).\n", "properties": { "name": { "type": "string", "description": "Customer's full name.", "example": "John Doe" }, "document": { "type": "string", "description": "Customer's document number.", "example": "853.513.468-93" } } }, "enrollment-customer-fields": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Customer Fields", "description": "Full set of customer data fields provided when creating an enrollment (contact + identity).\nComposes the shared contact and identity fragments. Used by payment types that need the\ncomplete customer data (e.g. Pix Automatico, MP Connect).\n", "allOf": [ { "$ref": "#/components/schemas/enrollment-contact-fields" }, { "$ref": "#/components/schemas/enrollment-identity-fields" } ] }, "subscription": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Subscription", "description": "Subscription details for recurring enrollment payments.\nShared between ws/direct (enrollment+charge) and ws/userenrollment (standalone enrollment).\nThe `required` constraint is context- and payment-type-dependent. See the composing\npayment or enrollment request schema for the required fields.\n", "properties": { "expiration_date": { "type": "string", "format": "date", "description": "Subscription expiration date.\n", "example": "2026-01-15" }, "fixed_amount": { "type": "string", "nullable": true, "description": "Fixed amount for subscription (mutually exclusive with max_amount_floor).\n", "example": "99.85" }, "frequency": { "type": "string", "description": "Subscription frequency.\n", "enum": [ "onetime", "daily", "weekly", "fortnightly", "monthly", "bimonthly", "quarterly", "halfyearly", "yearly", "biennially", "ondemand" ], "example": "monthly" }, "frequency_qtd": { "type": "string", "description": "Quantity for the configured frequency (e.g. every N periods).\n", "example": "1" }, "max_amount": { "type": "string", "description": "Maximum amount for variable subscriptions.\n", "example": "500.00" }, "max_amount_floor": { "type": "string", "nullable": true, "description": "Maximum amount floor for variable subscriptions (mutually exclusive with fixed_amount).\n", "example": "99.85" }, "min_amount": { "type": "string", "description": "Minimum amount for variable subscriptions.\n", "example": "10.00" }, "recurrence_rule": { "type": "string", "description": "Recurrence rule for the subscription.\n", "enum": [ "after", "before", "on" ], "example": "before" }, "recurrence_value": { "type": "string", "description": "Recurrence value associated with the recurrence rule.\n", "example": "1" }, "retry": { "type": "string", "description": "Retry strategy for failed payments.\n", "enum": [ "allow_3R_7D", "not_allowed" ], "example": "allow_3R_7D" }, "start_date": { "type": "string", "format": "date", "description": "Subscription start date (must be at least 24 hours in the future).\n", "example": "2025-01-15" }, "subscription_name": { "type": "string", "description": "Description/name of the subscription.\n", "maxLength": 35, "example": "Monthly subscription" } } }, "enrollment-with-subscription": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment with Subscription", "description": "Enrollment data for payment methods that support enrollment creation combined with\ncharge execution via /ws/direct.\nIncludes subscription details for configuring the recurring payment terms.\nWhen creating an enrollment alongside the charge, customer data fields\nmay also be provided.\n", "allOf": [ { "$ref": "#/components/schemas/direct-enrollment" }, { "$ref": "#/components/schemas/enrollment-customer-fields" }, { "type": "object", "title": "Enrollment With Subscription Extra Fields", "properties": { "subscription": { "allOf": [ { "$ref": "#/components/schemas/subscription" }, { "required": [ "subscription_name", "frequency" ] } ] } } } ] }, "not-nullable-datetime": { "x-hidden": true, "title": "Datetime", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) ([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])$", "description": "Date and time." }, "mpconnect-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Mercado Pago Connect Request", "description": "Mercado Pago Connect recurring payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\nRequires prior customer enrollment via /ws/userenrollment/mpconnect.\n", "properties": { "enrollment": { "$ref": "#/components/schemas/enrollment-with-subscription" }, "payment_type_code": { "type": "string", "description": "Set to **mpconnect** for Mercado Pago Connect recurring payments.", "enum": [ "mpconnect" ], "example": "mpconnect" }, "metadata": { "type": "object", "title": "Metadata", "description": "Additional metadata for the payment.\n", "properties": { "device_channel": { "type": "string", "description": "The device channel used by the customer.\n", "example": "Others" }, "external_customer_id": { "type": "string", "example": "customer-12345", "description": "External customer identifier in the merchant's system.\n" }, "risk": { "type": "object", "title": "Risk", "description": "Risk assessment information.\n", "properties": { "recurring_payment": { "type": "boolean", "description": "Whether this is a recurring payment.\n", "example": true }, "customer_account_create_date": { "allOf": [ { "$ref": "#/components/schemas/not-nullable-datetime" } ], "description": "Date when the customer account was created.\n", "example": "2024-01-15 10:30:00" } } }, "merchant_enrollment_code": { "type": "string", "example": "enrollment-123", "x-conditional": "Required for recurring charges", "description": "The enrollment code from a confirmed customer enrollment.\n" } } } } }, "mpconnect": { "x-schema-group": "Requests", "title": "Argentina Mercado Pago Connect Payment Request", "description": "Mercado Pago Connect recurring payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "$ref": "#/components/schemas/mpconnect-request-base" } ] }, "pago-facil": { "x-schema-group": "Requests", "title": "Argentina Pago Facil Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "type": "object", "title": "Pago Facil Extra Fields", "properties": { "document": { "type": "string", "example": "23876543214" }, "payment_type_code": { "description": "The value must be pagofacil for PagoFacil payments.", "type": "string", "example": "pagofacil", "enum": [ "pagofacil" ] }, "currency_code": { "type": "string", "example": "ARS" } } } ] }, "rapi-pago": { "x-schema-group": "Requests", "title": "Argentina Rapi Pago Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "type": "object", "title": "RapiPago Extra Fields", "properties": { "document": { "type": "string", "example": "23876543214" }, "payment_type_code": { "description": "The value must be rapipago for RapiPago payments.", "type": "string", "example": "rapipago", "enum": [ "rapipago" ] }, "currency_code": { "type": "string", "example": "ARS" } } } ] }, "stablecoin-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Stablecoin Request", "description": "Stablecoin payment request. This is a multi-country payment method —\nthe same integration works across all supported countries with minimal changes\n(country, currency, and document fields).\nCustomers pay using blockchain-based stablecoins (USDC or USDT).\nThe `payment_type_code` should be set to the specific stablecoin: `usdc` or `usdt`.\n", "properties": { "payment_type_code": { "type": "string", "description": "Set to **usdc** for USD Coin or **usdt** for Tether stablecoin payments.", "enum": [ "usdc", "usdt" ], "example": "usdt" }, "currency_code": { "type": "string", "description": "The source currency code (ISO 4217 three-letter code or stablecoin ticker).\n", "enum": [ "ARS", "BRL", "CLP", "MXN", "PEN", "USD", "USDC", "USDT", "UYU" ], "maxLength": 4, "example": "USDT" }, "protocol": { "type": "string", "description": "The blockchain protocol/network the customer will use to pay.\nWhen provided, the crypto wallet page pre-selects this network and skips\nthe network-selection step. Matches the `protocol` returned in the\ncryptocurrency response.\n", "enum": [ "ARBITRUM", "ARC", "BASE", "BEP20", "ERC20", "POLYGON", "SOL", "STELLAR", "TRC20" ], "example": "TRC20" }, "birth_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "description": "Customer's date of birth.\n", "example": "15/03/1990" } } }, "stablecoin": { "x-schema-group": "Requests", "title": "Argentina Stablecoin Payment Request", "description": "Stablecoin payment request. This is a multi-country payment method —\nthe same integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ar-request-base" }, { "$ref": "#/components/schemas/stablecoin-request-base" } ] }, "payment": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇦🇷 Argentina", "oneOf": [ { "$ref": "#/components/schemas/card" }, { "$ref": "#/components/schemas/banktransfer" }, { "$ref": "#/components/schemas/cupon" }, { "$ref": "#/components/schemas/debin" }, { "$ref": "#/components/schemas/mercadopago" }, { "$ref": "#/components/schemas/mpconnect" }, { "$ref": "#/components/schemas/pago-facil" }, { "$ref": "#/components/schemas/rapi-pago" }, { "$ref": "#/components/schemas/stablecoin" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card", "cabal": "#/components/schemas/card", "creditcard": "#/components/schemas/card", "debitcard": "#/components/schemas/card", "diners": "#/components/schemas/card", "mastercard": "#/components/schemas/card", "naranja": "#/components/schemas/card", "visa": "#/components/schemas/card", "banktransfer": "#/components/schemas/banktransfer", "cupon": "#/components/schemas/cupon", "debin": "#/components/schemas/debin", "mercadopago": "#/components/schemas/mercadopago", "mpconnect": "#/components/schemas/mpconnect", "mpcredito": "#/components/schemas/mercadopago", "pagofacil": "#/components/schemas/pago-facil", "rapipago": "#/components/schemas/rapi-pago", "usdc": "#/components/schemas/stablecoin", "usdt": "#/components/schemas/stablecoin" } } }, "pagos-net": { "x-schema-group": "Requests", "title": "Bolivia PagosNet Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "PagosNet Extra Fields", "properties": { "country": { "description": "The two-letter country code for the customer country.\n", "type": "string", "example": "bo", "enum": [ "bo" ] }, "payment_type_code": { "description": "Value must be pagosnet for PagosNet payments.", "type": "string", "example": "pagosnet", "enum": [ "pagosnet" ] }, "currency_code": { "type": "string", "example": "BOB", "enum": [ "BOB", "USD" ], "minLength": 3, "maxLength": 3 }, "address": { "type": "string", "example": "Calle Comercio 100" }, "zipcode": { "type": "string", "example": "0000" }, "city": { "type": "string", "example": "La Paz" }, "state": { "type": "string", "example": "LP" }, "phone_number": { "type": "string", "example": "+59171234567" }, "document": { "type": "string", "example": "1234567" } } } ] }, "payment-2": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇧🇴 Bolivia", "oneOf": [ { "$ref": "#/components/schemas/pagos-net" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "pagosnet": "#/components/schemas/pagos-net" } } }, "br-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Brazil Request Base", "properties": { "document": { "description": "Customer's CPF (natural person) or CNPJ (business) number.\n" }, "country": { "type": "string", "example": "br", "enum": [ "br" ] }, "currency_code": { "type": "string", "example": "BRL", "enum": [ "BRL", "EUR", "GBP", "USD" ] }, "state": { "type": "string", "example": "CE", "enum": [ "AC", "AL", "AM", "AP", "BA", "CE", "DF", "ES", "GO", "MA", "MG", "MS", "MT", "PA", "PB", "PE", "PI", "PR", "RJ", "RN", "RO", "RR", "RS", "SC", "SE", "SP", "TO" ] } } }, "card-2": { "x-schema-group": "Requests", "title": "Brazil Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "diners", "elo", "hipercard", "mastercard", "visa" ] }, "threeds_eci": { "type": "string", "x-conditional": "Required for debit card transactions in Brazil.", "description": "ECI (Electronic Commerce Indicator) returned by the Directory Servers to indicate authentication result.\n", "example": "05", "minLength": 1, "maxLength": 2 }, "threeds_cryptogram": { "type": "string", "x-conditional": "Required for debit card transactions in Brazil.", "description": "Cryptogram hash representing the 3DS authentication.\n", "example": "AAIBAkl0NwmHglFBAXQ3AAAAAAA=" } } } ] }, "directdebit": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Direct Debit Data", "description": "Direct debit payment data containing bank account information.\n", "properties": { "bank_code": { "type": "string", "description": "The bank code for the direct debit.\n", "maxLength": 5, "example": "033" }, "bank_agency": { "type": "string", "description": "The bank agency (branch) number.\n", "example": "1312-0" }, "bank_account": { "type": "string", "description": "The bank account number.\n", "example": "13123-5" } } }, "banktransfer-2": { "x-schema-group": "Requests", "title": "Brazil Bank Transfer Payment Request", "description": "Bank transfer payment request for Brazil.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Banktransfer Extra Fields", "properties": { "payment_type_code": { "description": "Value must be banktransfer for Bank Transfer payments.", "type": "string", "example": "banktransfer", "enum": [ "banktransfer" ] }, "directdebit": { "$ref": "#/components/schemas/directdebit" } } } ] }, "boleto": { "x-schema-group": "Requests", "title": "Brazil Boleto Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Boleto Extra Fields", "properties": { "payment_type_code": { "description": "Value must be boleto for Boleto Bancário payments.", "type": "string", "example": "boleto", "enum": [ "boleto" ] }, "due_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "example": "31/12/2027", "description": "The due date for payment slips (boleto expiry date).\nIt can be more than three days only when payment.currency is BRL (Brazilian Real),\nand your merchant account has this feature enabled.\nThe due date is based on the local time of the country that the payment is generated.\nPlease note the boleto may not be cancelled right after the expire date(3 days for USD) in order to\nhave a proper compensation period specially when the boleto is paid close to a public holiday.\nAlso, if the expire date is on holiday or weekend, we need to always consider the next business day.\n" } } } ] }, "boleto-pix": { "x-schema-group": "Requests", "title": "Brazil BoletoPix Payment Request", "description": "Boleto Pix hybrid payment — boleto with Pix as fallback.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Boleto Pix Extra Fields", "properties": { "payment_type_code": { "description": "Value must be boletopix for Boleto Pix payments.", "type": "string", "example": "boletopix", "enum": [ "boletopix" ] } } } ] }, "directdebit-2": { "x-hidden": true, "x-schema-group": "Requests", "title": "Brazil Direct Debit Payment Request", "description": "Direct debit payment request for Brazil. Requires bank account information\nfor debiting the customer's bank account.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Directdebit Extra Fields", "required": [ "directdebit" ], "properties": { "payment_type_code": { "description": "Value must be directdebit for Direct Debit payments.", "type": "string", "example": "directdebit", "enum": [ "directdebit" ] }, "directdebit": { "$ref": "#/components/schemas/directdebit" } } } ] }, "ebx-banktransfer-sub": { "x-schema-group": "Requests", "title": "Brazil Bank Transfer Subscription Payment Request", "description": "EBANX bank transfer subscription payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Ebx Banktransfer Sub Extra Fields", "properties": { "payment_type_code": { "description": "Value must be ebx-banktransfer-sub for bank transfer subscription payments.", "type": "string", "example": "ebx-banktransfer-sub", "enum": [ "ebx-banktransfer-sub" ] } } } ] }, "mercadopago-2": { "x-schema-group": "Requests", "title": "Brazil Mercado Pago Wallet Payment Request", "description": "Mercado Pago Wallet payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "$ref": "#/components/schemas/mercadopago-request-base" } ] }, "mpconnect-2": { "x-schema-group": "Requests", "title": "Brazil Mercado Pago Connect Payment Request", "description": "Mercado Pago Connect recurring payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "$ref": "#/components/schemas/mpconnect-request-base" } ] }, "nu-pay": { "x-schema-group": "Requests", "title": "Brazil NuPay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "NuPay Extra Fields", "properties": { "redirect_url": { "type": "string", "description": "URL to redirect customer after payment completion.\n", "example": "https://merchant.example.com/callback" }, "payment_type_code": { "description": "The value must be \"nupay\" for NuPay payments.", "type": "string", "example": "nupay", "enum": [ "nupay" ] }, "currency_code": { "description": "Currency code for NuPay. Only BRL is supported.\n", "enum": [ "BRL" ] } } } ] }, "nu-pay-recurring": { "x-schema-group": "Requests", "title": "Brazil NuPay Recurring Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "NuPay Recurring Extra Fields", "properties": { "enrollment": { "allOf": [ { "$ref": "#/components/schemas/direct-enrollment" }, { "type": "object", "title": "NuPay Recurring Enrollment Extra Fields", "properties": { "source": { "type": "string", "enum": [ "app", "web" ], "example": "app", "description": "NuPay authorization flow used to create the agreement.\n- `app`: App-to-App flow. The customer is redirected to the NuPay app through a deeplink.\n- `web`: Web-to-App flow. The customer receives a push notification in the NuPay app.\n\nWhen informed, the customer CPF is required.\nWhen omitted, the flow is selected by the customer CPF: Web-to-App when it is informed, App-to-App otherwise.\n" } } } ] }, "document": { "description": "Customer's document number.\nRequires a valid CPF (Natural person taxpayer ID) or CNPJ (business taxpayer ID).\n" }, "payment_type_code": { "description": "Value must be nupay-recurrent for NuPay Recurring payments.", "type": "string", "example": "nupay-recurrent", "enum": [ "nupay-recurrent" ] }, "due_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "example": "31/12/2027", "description": "Expiry date of the payment. The customer must complete the NuPay payment before this date,\notherwise the payment expires.\nThe due date is based on the local time of the country where the payment is generated\n(America/Sao_Paulo for Brazil).\nWhen omitted, it defaults to 2 days from the payment creation date for Brazilian e-wallets.\n" }, "metadata": { "type": "object", "title": "Metadata", "description": "Metadata object containing additional payment configuration.", "required": [ "merchant_enrollment_code" ], "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant Enrollment code", "example": "d057c598" } } } } } ] }, "paypal": { "x-schema-group": "Requests", "title": "Brazil PayPal Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "PayPal Extra Fields", "properties": { "enrollment": { "$ref": "#/components/schemas/direct-enrollment" }, "payment_type_code": { "description": "The value must be \"paypal\" for PayPal payments.", "type": "string", "example": "paypal", "enum": [ "paypal" ] }, "currency_code": { "description": "Currency code for PayPal. Only BRL is supported.\n", "enum": [ "BRL" ] } } } ] }, "pic-pay": { "x-schema-group": "Requests", "title": "Brazil PicPay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "PicPay Extra Fields", "properties": { "payment_type_code": { "description": "The value must be \"picpay\" for PicPay payments.", "type": "string", "example": "picpay", "enum": [ "picpay" ] }, "currency_code": { "description": "Currency code for PicPay. Only BRL is supported.\n", "enum": [ "BRL" ] } } } ] }, "pix": { "x-schema-group": "Requests", "title": "Brazil Pix Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Pix Extra Fields", "properties": { "amount_hide": { "type": "boolean", "example": true, "description": "Whether to hide the amount from the customer. Only applicable to Pix payments.\n" }, "payment_type_code": { "description": "Value must be pix for Pix payments.", "type": "string", "example": "pix", "enum": [ "pix" ] }, "due_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "example": "31/12/2027", "description": "Expiration date of the Pix QR code / payment link.\nFor Pix payments this field cannot be set by the merchant: any value sent in the request is\nignored and the due date is derived automatically from `expiration_time_in_seconds`\n(defaulting to 5 hours when not provided, or to the merchant's configured payment link expiration).\nThe due date is based on the local time of the country where the payment is generated\n(America/Sao_Paulo for Brazil).\n" }, "currency_code": { "enum": [ "BRL", "USD" ] } } } ] }, "pix-automatico": { "x-schema-group": "Requests", "title": "Brazil Pix Automatico Payment Request", "description": "A JSON object that represents a Pix Automatico charge execution via ws/direct.\nThis schema is for executing a payment against an existing Pix Automatico enrollment.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Pix Automatico Extra Fields", "properties": { "payment_type_code": { "description": "Value must be pix-automatico for Pix Automatico payments.", "type": "string", "example": "pix-automatico", "enum": [ "pix-automatico" ] }, "metadata": { "type": "object", "title": "Metadata", "description": "Metadata object containing additional payment configuration.", "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant-provided enrollment identifier linking this charge to an existing enrollment.\n", "example": "enrollment-123" } } }, "enrollment": { "allOf": [ { "$ref": "#/components/schemas/enrollment-with-subscription" }, { "type": "object", "title": "Pix Automatico Enrollment Extra Fields", "properties": { "name": { "type": "string", "description": "Customer's full name (Pix Automatico enforces 1 to 140 characters).", "minLength": 1, "maxLength": 140, "example": "John Doe" } } } ] } } } ] }, "pix-pisp": { "x-hidden": true, "x-schema-group": "Requests", "title": "Brazil Pix PISP Payment Request", "description": "Pix PISP (Payment Initiation Service Provider) payment request for Brazil.\nUses the Pix instant payment system via a payment initiation service provider.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "type": "object", "title": "Pix Pisp Extra Fields", "properties": { "payment_type_code": { "description": "Value must be pix-pisp for Pix PISP payments.", "type": "string", "example": "pix-pisp", "enum": [ "pix-pisp" ] }, "currency_code": { "enum": [ "BRL", "USD" ] }, "pisp": { "type": "object", "title": "Pisp", "description": "PISP (Payment Initiation Service Provider) bank information for Pix PISP payments.\n", "properties": { "bank_id": { "type": "string", "example": "237", "description": "The bank identifier for the PISP payment initiation.\n" } } } } } ] }, "stablecoin-2": { "x-schema-group": "Requests", "title": "Brazil Stablecoin Payment Request", "description": "Stablecoin payment request. This is a multi-country payment method —\nthe same integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/br-request-base" }, { "$ref": "#/components/schemas/stablecoin-request-base" } ] }, "payment-3": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇧🇷 Brazil", "oneOf": [ { "$ref": "#/components/schemas/card-2" }, { "$ref": "#/components/schemas/banktransfer-2" }, { "$ref": "#/components/schemas/boleto-pix" }, { "$ref": "#/components/schemas/boleto" }, { "$ref": "#/components/schemas/directdebit-2" }, { "$ref": "#/components/schemas/ebx-banktransfer-sub" }, { "$ref": "#/components/schemas/mercadopago-2" }, { "$ref": "#/components/schemas/mpconnect-2" }, { "$ref": "#/components/schemas/nu-pay-recurring" }, { "$ref": "#/components/schemas/nu-pay" }, { "$ref": "#/components/schemas/paypal" }, { "$ref": "#/components/schemas/pic-pay" }, { "$ref": "#/components/schemas/pix-automatico" }, { "$ref": "#/components/schemas/pix-pisp" }, { "$ref": "#/components/schemas/pix" }, { "$ref": "#/components/schemas/stablecoin-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-2", "creditcard": "#/components/schemas/card-2", "debitcard": "#/components/schemas/card-2", "diners": "#/components/schemas/card-2", "elo": "#/components/schemas/card-2", "hipercard": "#/components/schemas/card-2", "mastercard": "#/components/schemas/card-2", "visa": "#/components/schemas/card-2", "banktransfer": "#/components/schemas/banktransfer-2", "boleto": "#/components/schemas/boleto", "boletopix": "#/components/schemas/boleto-pix", "directdebit": "#/components/schemas/directdebit-2", "ebx-banktransfer-sub": "#/components/schemas/ebx-banktransfer-sub", "mercadopago": "#/components/schemas/mercadopago-2", "mpconnect": "#/components/schemas/mpconnect-2", "mpcredito": "#/components/schemas/mercadopago-2", "nupay": "#/components/schemas/nu-pay", "nupay-recurrent": "#/components/schemas/nu-pay-recurring", "paypal": "#/components/schemas/paypal", "picpay": "#/components/schemas/pic-pay", "pix": "#/components/schemas/pix", "pix-automatico": "#/components/schemas/pix-automatico", "pix-pisp": "#/components/schemas/pix-pisp", "usdc": "#/components/schemas/stablecoin-2", "usdt": "#/components/schemas/stablecoin-2" } } }, "cl-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Chile Request Base", "properties": { "document": { "description": "Customer's RUT (taxpayer identification number).\n", "type": "string", "example": "9882884-2" }, "country": { "type": "string", "example": "cl", "enum": [ "cl" ] }, "currency_code": { "type": "string", "example": "CLP", "enum": [ "CLP", "EUR", "USD" ] }, "address": { "type": "string", "example": "Calle Ahumada 200" }, "zipcode": { "type": "string", "example": "8320000" }, "city": { "type": "string", "example": "Santiago" }, "state": { "type": "string", "example": "RM" }, "phone_number": { "type": "string", "example": "+56912345678" }, "eft_code": { "type": "string", "example": "banco_estado_chile", "description": "EFT (Electronic Funds Transfer) bank code for Chile.\n" } } }, "card-3": { "x-schema-group": "Requests", "title": "Chile Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "diners", "mastercard", "visa" ] } } } ] }, "bank-transfer": { "x-schema-group": "Requests", "title": "Chile Bank Transfer Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "type": "object", "title": "Bank Transfer Extra Fields", "properties": { "payment_type_code": { "description": "Value must be banktransfer for Bank Transfer payments.", "type": "string", "example": "banktransfer", "enum": [ "banktransfer" ] } } } ] }, "mach-pay": { "x-schema-group": "Requests", "title": "Chile MACH Pay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "type": "object", "title": "MACH Extra Fields", "properties": { "payment_type_code": { "description": "The value must be \"machpay\" for MACH Pay payments.", "type": "string", "example": "machpay", "enum": [ "machpay" ] }, "currency_code": { "description": "Currency code for MACH Pay.\n", "enum": [ "CLP", "EUR", "USD" ] } } } ] }, "mercadopago-3": { "x-schema-group": "Requests", "title": "Chile Mercado Pago Wallet Payment Request", "description": "Mercado Pago Wallet payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "$ref": "#/components/schemas/mercadopago-request-base" } ] }, "mpconnect-3": { "x-schema-group": "Requests", "title": "Chile Mercado Pago Connect Payment Request", "description": "Mercado Pago Connect recurring payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "$ref": "#/components/schemas/mpconnect-request-base" } ] }, "multicaja": { "x-schema-group": "Requests", "title": "Chile Multicaja Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "type": "object", "title": "Multicaja Extra Fields", "properties": { "payment_type_code": { "description": "Value must be multicaja for Multicaja payments.", "type": "string", "example": "multicaja", "enum": [ "multicaja" ] }, "currency_code": { "description": "Currency code for Multicaja.\n", "enum": [ "CLP", "EUR", "USD" ] } } } ] }, "sencillito": { "x-schema-group": "Requests", "title": "Chile Sencillito Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "type": "object", "title": "Sencillito Extra Fields", "properties": { "payment_type_code": { "description": "Value must be sencillito for Sencillito payments.", "type": "string", "example": "sencillito", "enum": [ "sencillito" ] }, "currency_code": { "description": "Currency code for Sencillito.\n", "enum": [ "CLP", "EUR", "USD" ] } } } ] }, "servipag": { "x-schema-group": "Requests", "title": "Chile Servipag Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "type": "object", "title": "Servipag Extra Fields", "properties": { "document": { "description": "Customer's RUT (taxpayer identification number).\n" }, "payment_type_code": { "description": "Value must be servipag for Servipag payments.", "type": "string", "example": "servipag", "enum": [ "servipag" ] }, "currency_code": { "enum": [ "CLP", "EUR", "USD" ] } } } ] }, "stablecoin-3": { "x-schema-group": "Requests", "title": "Chile Stablecoin Payment Request", "description": "Stablecoin payment request. This is a multi-country payment method —\nthe same integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "$ref": "#/components/schemas/stablecoin-request-base" } ] }, "web-pay": { "x-schema-group": "Requests", "title": "Chile WebPay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cl-request-base" }, { "type": "object", "title": "Webpay Extra Fields", "properties": { "document": { "description": "Customer's document number.\n- Customer RUT (taxpayer identification number).\n" }, "payment_type_code": { "description": "Value must be webpay, webpay-rest, or webpayplus for Webpay payments.", "type": "string", "example": "webpay", "enum": [ "webpay", "webpay-rest", "webpayplus" ] }, "currency_code": { "enum": [ "CLP", "EUR", "USD" ] } } } ] }, "payment-4": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇨🇱 Chile", "oneOf": [ { "$ref": "#/components/schemas/card-3" }, { "$ref": "#/components/schemas/bank-transfer" }, { "$ref": "#/components/schemas/mach-pay" }, { "$ref": "#/components/schemas/mercadopago-3" }, { "$ref": "#/components/schemas/mpconnect-3" }, { "$ref": "#/components/schemas/multicaja" }, { "$ref": "#/components/schemas/sencillito" }, { "$ref": "#/components/schemas/servipag" }, { "$ref": "#/components/schemas/stablecoin-3" }, { "$ref": "#/components/schemas/web-pay" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-3", "creditcard": "#/components/schemas/card-3", "debitcard": "#/components/schemas/card-3", "diners": "#/components/schemas/card-3", "mastercard": "#/components/schemas/card-3", "visa": "#/components/schemas/card-3", "banktransfer": "#/components/schemas/bank-transfer", "machpay": "#/components/schemas/mach-pay", "mercadopago": "#/components/schemas/mercadopago-3", "mpconnect": "#/components/schemas/mpconnect-3", "mpcredito": "#/components/schemas/mercadopago-3", "multicaja": "#/components/schemas/multicaja", "sencillito": "#/components/schemas/sencillito", "servipag": "#/components/schemas/servipag", "usdc": "#/components/schemas/stablecoin-3", "usdt": "#/components/schemas/stablecoin-3", "webpay": "#/components/schemas/web-pay", "webpay-rest": "#/components/schemas/web-pay", "webpayplus": "#/components/schemas/web-pay" } } }, "co-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Colombia Request Base", "properties": { "document": { "description": "Customer's identification number (CC, CE, or NIT).\n", "type": "string", "example": "4023030074" }, "country": { "type": "string", "example": "co", "enum": [ "co" ] }, "currency_code": { "type": "string", "example": "COP", "enum": [ "COP" ] }, "address": { "type": "string", "example": "Carrera 7 #32-16" }, "zipcode": { "type": "string", "example": "110111" }, "city": { "type": "string", "example": "Bogotá" }, "state": { "type": "string", "example": "DC" }, "phone_number": { "type": "string", "example": "+573001234567" } } }, "card-4": { "x-schema-group": "Requests", "title": "Colombia Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "codensa", "creditcard", "debitcard", "diners", "elo", "mastercard", "visa" ] }, "currency_code": { "enum": [ "COP", "EUR", "USD" ] } } } ] }, "pse-avanza": { "x-schema-group": "Requests", "title": "Colombia PSE Avanza Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "PSE Avanza Extra Fields", "properties": { "document_type": { "type": "string", "description": "Customer's document type.\n- **CC** - Customer Cedula de Ciudadania\n- **CE** - Cédula de Extrangeria\n- **NIT** - Taxpayer Id Number.\n", "maxLength": 32, "enum": [ "CC", "CE", "NIT" ], "example": "CC" }, "payment_type_code": { "description": "Set to **achpse** or **eft** for PSE Avanza payments.", "type": "string", "example": "achpse", "enum": [ "achpse", "eft" ] }, "bank_code": { "type": "string", "description": "Customer selected bank.\nThe `bank_code` in your payment request must be set to the `code` retrieved from the response of the **/getBankList** endpoint.\n", "example": "1815" }, "currency_code": { "enum": [ "COP", "EUR", "USD" ] }, "eft_code": { "type": "string", "description": "EFT bank code identifier (e.g. 'bancolombia'). Used as an alternative bank identifier\nfor EFT payments.\n", "example": "bancolombia" }, "bank_details": { "$ref": "#/components/schemas/bank-details" } } } ] }, "baloto": { "x-schema-group": "Requests", "title": "Colombia Baloto Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Baloto Extra Fields", "properties": { "payment_type_code": { "description": "The value must be \"baloto\" for Baloto payments.", "type": "string", "example": "baloto", "enum": [ "baloto" ] }, "currency_code": { "enum": [ "COP", "EUR", "USD" ] } } } ] }, "bancolombia": { "x-schema-group": "Requests", "title": "Colombia Boton Bancolombia Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Bancolombia Extra Fields", "properties": { "operation": { "type": "string", "x-conditional": "Required for Bancolombia Button", "description": "The operation type.\n", "example": "request" }, "payment_type_code": { "description": "The value must be \"bancolombia-button\" for Bancolombia payments.", "type": "string", "example": "bancolombia-button", "enum": [ "bancolombia-button" ] }, "currency_code": { "enum": [ "COP" ] } } } ] }, "breb": { "x-schema-group": "Requests", "title": "Colombia Bre-B Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Bre-B Extra Fields", "properties": { "payment_type_code": { "description": "The value must be \"breb\" for Bre-B payments.", "type": "string", "example": "breb", "enum": [ "breb" ] }, "currency_code": { "enum": [ "COP" ] } } } ] }, "efecty": { "x-schema-group": "Requests", "title": "Colombia Efecty Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Efecty Extra Fields", "properties": { "payment_type_code": { "description": "The value must be \"efecty\" for Efecty payments.", "type": "string", "example": "efecty", "enum": [ "efecty" ] }, "currency_code": { "enum": [ "COP", "EUR", "USD" ] } } } ] }, "movii": { "x-schema-group": "Requests", "title": "Colombia Movii Payment Request", "description": "Movii wallet payment request for Colombia.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Movii Extra Fields", "properties": { "payment_type_code": { "description": "Value must be movii for Movii wallet payments.", "type": "string", "example": "movii", "enum": [ "movii" ] } } } ] }, "nequi": { "x-schema-group": "Requests", "title": "Colombia Nequi Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Nequi Extra Fields", "properties": { "redirect_url": { "type": "string", "description": "URL to redirect customer after payment completion.\n", "example": "https://merchant.example.com/callback" }, "payment_type_code": { "description": "The value must be \"nequi\" for Nequi payments.", "type": "string", "example": "nequi", "enum": [ "nequi" ] }, "currency_code": { "enum": [ "COP" ] } } } ] }, "nequi-recurring": { "x-schema-group": "Requests", "title": "Colombia Nequi Recurring Payment Request", "description": "A JSON object that represents a Nequi Recurring charge execution via ws/direct.\nThis schema is for executing a payment against an existing Nequi Recurring enrollment.\nThe operation field is not required — it is automatically set to 'request' by the system\nfor all ws/direct calls (via OperationDefaultValueMorpher).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Nequi Recurring Extra Fields", "properties": { "payment_type_code": { "description": "Value must be nequi-recurrent for Nequi Recurring payments.", "type": "string", "example": "nequi-recurrent", "enum": [ "nequi-recurrent" ] }, "metadata": { "type": "object", "title": "Metadata", "description": "Metadata object containing additional payment configuration.", "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant-provided enrollment identifier linking this charge to an existing enrollment.\n", "example": "enrollment-nequi-123" } } }, "enrollment": { "$ref": "#/components/schemas/direct-enrollment" } } } ] }, "transfiya": { "x-schema-group": "Requests", "title": "Colombia Transfiya Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/co-request-base" }, { "type": "object", "title": "Transfiya Extra Fields", "properties": { "payment_type_code": { "description": "The value must be \"transfiya\" for Transfiya payments.", "type": "string", "example": "transfiya", "enum": [ "transfiya" ] }, "currency_code": { "enum": [ "COP" ] } } } ] }, "payment-5": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇨🇴 Colombia", "oneOf": [ { "$ref": "#/components/schemas/card-4" }, { "$ref": "#/components/schemas/baloto" }, { "$ref": "#/components/schemas/bancolombia" }, { "$ref": "#/components/schemas/breb" }, { "$ref": "#/components/schemas/efecty" }, { "$ref": "#/components/schemas/movii" }, { "$ref": "#/components/schemas/nequi-recurring" }, { "$ref": "#/components/schemas/nequi" }, { "$ref": "#/components/schemas/pse-avanza" }, { "$ref": "#/components/schemas/transfiya" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-4", "codensa": "#/components/schemas/card-4", "creditcard": "#/components/schemas/card-4", "debitcard": "#/components/schemas/card-4", "diners": "#/components/schemas/card-4", "elo": "#/components/schemas/card-4", "mastercard": "#/components/schemas/card-4", "visa": "#/components/schemas/card-4", "achpse": "#/components/schemas/pse-avanza", "baloto": "#/components/schemas/baloto", "bancolombia-button": "#/components/schemas/bancolombia", "breb": "#/components/schemas/breb", "efecty": "#/components/schemas/efecty", "eft": "#/components/schemas/pse-avanza", "movii": "#/components/schemas/movii", "nequi": "#/components/schemas/nequi", "nequi-recurrent": "#/components/schemas/nequi-recurring", "transfiya": "#/components/schemas/transfiya" } } }, "cr-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Costa Rica Request Base", "properties": { "document": { "description": "Customer's cédula de identidad number.\n", "type": "string", "example": "117520828" }, "country": { "type": "string", "example": "cr", "enum": [ "cr" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "CRC", "USD" ] }, "address": { "type": "string", "example": "Avenida Central 100" }, "zipcode": { "type": "string", "example": "10101" }, "city": { "type": "string", "example": "San José" }, "state": { "type": "string", "example": "SJ" }, "phone_number": { "type": "string", "example": "+50612345678" } } }, "card-5": { "x-schema-group": "Requests", "title": "Costa Rica Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/cr-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "mastercard", "visa" ] }, "currency_code": { "enum": [ "CRC", "USD" ] } } } ] }, "payment-6": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇨🇷 Costa Rica", "oneOf": [ { "$ref": "#/components/schemas/card-5" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-5", "creditcard": "#/components/schemas/card-5", "debitcard": "#/components/schemas/card-5", "mastercard": "#/components/schemas/card-5", "visa": "#/components/schemas/card-5" } } }, "do-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Dominican Republic Request Base", "properties": { "document": { "description": "Customer's cédula de identidad number.\n", "type": "string", "example": "00112345678" }, "country": { "type": "string", "example": "do", "enum": [ "do" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "DOP", "USD" ] }, "address": { "type": "string", "example": "Calle El Conde 100" }, "zipcode": { "type": "string", "example": "10100" }, "city": { "type": "string", "example": "Santo Domingo" }, "state": { "type": "string", "example": "DN" }, "phone_number": { "type": "string", "example": "+18091234567" } } }, "card-6": { "x-schema-group": "Requests", "title": "Dominican Republic Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/do-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "mastercard", "visa" ] }, "currency_code": { "enum": [ "DOP", "USD" ] } } } ] }, "payment-7": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇩🇴 Dominican Republic", "oneOf": [ { "$ref": "#/components/schemas/card-6" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-6", "creditcard": "#/components/schemas/card-6", "debitcard": "#/components/schemas/card-6", "mastercard": "#/components/schemas/card-6", "visa": "#/components/schemas/card-6" } } }, "ec-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Ecuador Request Base", "properties": { "document": { "description": "Customer's cédula de identidad or RUC number.\n", "type": "string", "example": "1710034065" }, "country": { "type": "string", "example": "ec", "enum": [ "ec" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "USD" ] }, "address": { "type": "string", "example": "Av. Amazonas 100" }, "zipcode": { "type": "string", "example": "170150" }, "city": { "type": "string", "example": "Quito" }, "state": { "type": "string", "example": "P" }, "phone_number": { "type": "string", "example": "+593991234567" } } }, "card-7": { "x-schema-group": "Requests", "title": "Ecuador Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ec-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "mastercard", "visa" ] }, "currency_code": { "enum": [ "USD" ] } } } ] }, "safety-pay": { "x-schema-group": "Requests", "title": "Ecuador SafetyPay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "Safety Pay Extra Fields", "properties": { "country": { "description": "The two-letter country code for the customer country.\n", "type": "string", "example": "ec", "enum": [ "ec" ] }, "payment_type_code": { "description": "The payment method chosen by the customer.\n", "type": "string", "example": "safetypay-cash", "enum": [ "safetypay-cash", "safetypay-online" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "USD" ] }, "address": { "type": "string", "example": "Av. Amazonas 100" }, "zipcode": { "type": "string", "example": "170150" }, "city": { "type": "string", "example": "Quito" }, "state": { "type": "string", "example": "P" }, "phone_number": { "type": "string", "example": "+593991234567" }, "document": { "type": "string", "example": "1710034065" } } } ] }, "payment-8": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇪🇨 Ecuador", "oneOf": [ { "$ref": "#/components/schemas/card-7" }, { "$ref": "#/components/schemas/safety-pay" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-7", "creditcard": "#/components/schemas/card-7", "debitcard": "#/components/schemas/card-7", "mastercard": "#/components/schemas/card-7", "visa": "#/components/schemas/card-7", "safetypay-cash": "#/components/schemas/safety-pay", "safetypay-online": "#/components/schemas/safety-pay" } } }, "eg-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Egypt Request Base", "properties": { "country": { "type": "string", "example": "eg", "enum": [ "eg" ] }, "currency_code": { "type": "string", "example": "EGP", "enum": [ "EGP", "USD" ] }, "address": { "type": "string", "example": "123 El Tahrir St" }, "zipcode": { "type": "string", "example": "11511" }, "city": { "type": "string", "example": "Cairo" }, "state": { "type": "string", "example": "Cairo" }, "phone_number": { "type": "string", "example": "+201001234567" }, "document": { "type": "string", "example": "12345678901234" } } }, "fawry": { "x-schema-group": "Requests", "title": "Egypt Fawry Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/eg-request-base" }, { "type": "object", "title": "Fawry Extra Fields", "properties": { "payment_type_code": { "description": "Value must be fawry for Fawry payments.", "type": "string", "example": "fawry", "enum": [ "fawry" ] } } } ] }, "fawry-external": { "x-schema-group": "Requests", "title": "Egypt Fawry External Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/eg-request-base" }, { "type": "object", "title": "Fawry External Extra Fields", "properties": { "payment_type_code": { "description": "Value must be fawry-external for Fawry External payments.", "type": "string", "example": "fawry-external", "enum": [ "fawry-external" ] } } } ] }, "mobile-wallets": { "x-schema-group": "Requests", "title": "Egypt Mobile Wallets Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/eg-request-base" }, { "type": "object", "title": "Mobile Wallets Extra Fields", "properties": { "payment_type_code": { "description": "Value must be meeza for Mobile Wallets payments.", "type": "string", "example": "meeza", "enum": [ "meeza" ] } } } ] }, "payment-9": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇪🇬 Egypt", "oneOf": [ { "$ref": "#/components/schemas/fawry-external" }, { "$ref": "#/components/schemas/fawry" }, { "$ref": "#/components/schemas/mobile-wallets" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "fawry": "#/components/schemas/fawry", "fawry-external": "#/components/schemas/fawry-external", "meeza": "#/components/schemas/mobile-wallets" } } }, "mobile-money": { "x-schema-group": "Requests", "title": "Ghana Mobile Money Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "Mobile Money Extra Fields", "properties": { "country": { "description": "The two-letter country code for the customer country.\n", "type": "string", "example": "gh", "enum": [ "gh" ] }, "payment_type_code": { "description": "Choose a Ghana mobile network operator.\n", "type": "string", "example": "mpesa", "enum": [ "airtel", "mpesa", "mtn", "vodacom" ] }, "currency_code": { "type": "string", "example": "GHS", "enum": [ "GHS" ] }, "address": { "type": "string", "example": "123 Independence Ave" }, "zipcode": { "type": "string", "example": "GA001" }, "city": { "type": "string", "example": "Accra" }, "state": { "type": "string", "example": "AA" }, "phone_number": { "type": "string", "example": "+233201234567" }, "document": { "type": "string", "example": "GHA-123456789-0" } } } ] }, "payment-10": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇬🇭 Ghana", "oneOf": [ { "$ref": "#/components/schemas/mobile-money" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "airtel": "#/components/schemas/mobile-money", "mpesa": "#/components/schemas/mobile-money", "mtn": "#/components/schemas/mobile-money", "vodacom": "#/components/schemas/mobile-money" } } }, "gt-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Guatemala Request Base", "properties": { "document": { "description": "Customer's CUI (Código Único de Identidad) or NIT number.\n", "type": "string", "example": "1234567890101" }, "country": { "type": "string", "example": "gt", "enum": [ "gt" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "GTQ", "USD" ] }, "address": { "type": "string", "example": "6a Avenida 5-55 Zona 1" }, "zipcode": { "type": "string", "example": "01001" }, "city": { "type": "string", "example": "Ciudad de Guatemala" }, "state": { "type": "string", "example": "GU" }, "phone_number": { "type": "string", "example": "+50212345678" } } }, "card-8": { "x-schema-group": "Requests", "title": "Guatemala Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/gt-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "mastercard", "visa" ] }, "currency_code": { "enum": [ "GTQ", "USD" ] } } } ] }, "payment-11": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇬🇹 Guatemala", "oneOf": [ { "$ref": "#/components/schemas/card-8" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-8", "creditcard": "#/components/schemas/card-8", "debitcard": "#/components/schemas/card-8", "mastercard": "#/components/schemas/card-8", "visa": "#/components/schemas/card-8" } } }, "id-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Indonesia Request Base", "properties": { "country": { "type": "string", "example": "id", "enum": [ "id" ] }, "currency_code": { "type": "string", "example": "IDR", "enum": [ "IDR" ] }, "phone_number": { "type": "string", "example": "6281299221630" } } }, "dana": { "x-schema-group": "Requests", "title": "Indonesia DANA Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/id-request-base" }, { "type": "object", "title": "DANA Extra Fields", "properties": { "payment_type_code": { "description": "Value must be dana for DANA payments.", "type": "string", "example": "dana", "enum": [ "dana" ] } } } ] }, "ovo-recurring": { "x-schema-group": "Requests", "title": "Indonesia OVO Recurring Payment Request", "description": "A JSON object that represents an OVO Recurring charge linked to an accepted enrollment.\nThe enrollment must be created beforehand with `operation: enrollment`.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/id-request-base" }, { "type": "object", "title": "OVO Recurring Extra Fields", "required": [ "phone_number", "enrollment" ], "properties": { "payment_type_code": { "description": "Value must be ovo-recurring for OVO Recurring payments.", "type": "string", "example": "ovo-recurring", "enum": [ "ovo-recurring" ] }, "phone_number": { "type": "string", "description": "Customer phone number registered with OVO.", "maxLength": 30, "example": "6281299221630" }, "enrollment": { "type": "object", "title": "Enrollment", "description": "Reference to the accepted OVO Recurring enrollment.", "required": [ "merchant_enrollment_code" ], "properties": { "merchant_enrollment_code": { "type": "string", "description": "Unique identifier associated with the accepted enrollment.", "maxLength": 250, "example": "enrollment-ovo-recurring-123" }, "email": { "type": "string", "description": "Customer email.", "example": "john.doe@example.com" } } } } } ] }, "virtual-account": { "x-schema-group": "Requests", "title": "Indonesia Virtual Account Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/id-request-base" }, { "type": "object", "title": "Virtual Account Extra Fields", "required": [ "bank_details", "redirect_url" ], "properties": { "payment_type_code": { "description": "Value must be virtual-account for Virtual Account payments.", "type": "string", "example": "virtual-account", "enum": [ "virtual-account" ] }, "bank_details": { "type": "object", "title": "Bank Details", "description": "Bank that issues the Virtual Account number.", "required": [ "bank_code" ], "properties": { "bank_code": { "type": "string", "description": "Code of the bank that issues the Virtual Account number.", "example": "bca", "enum": [ "bca", "bnc", "bni", "bri", "bsi", "bss", "btn", "cimb", "danamon", "mandiri", "permata", "sinarmas" ] } } }, "redirect_url": { "type": "string", "description": "URL the customer is redirected to after completing the payment.", "example": "https://merchant.example.com/callback" } } } ] }, "payment-12": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇮🇩 Indonesia", "oneOf": [ { "$ref": "#/components/schemas/dana" }, { "$ref": "#/components/schemas/ovo-recurring" }, { "$ref": "#/components/schemas/virtual-account" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "dana": "#/components/schemas/dana", "ovo-recurring": "#/components/schemas/ovo-recurring", "virtual-account": "#/components/schemas/virtual-account" } } }, "card-9": { "x-schema-group": "Requests", "title": "India Card Payment Request", "description": "A JSON object that represents an initial card payment in India.\nThe `card` object with full card details is required.\nFor recurring payments using an existing enrollment, use the Card Recurring schema instead.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "zipcode": { "description": "Customer zip code.", "type": "string", "example": "400001" }, "address": { "type": "string", "example": "123 MG Road" }, "city": { "type": "string", "example": "Mumbai" }, "state": { "type": "string", "example": "MH" }, "phone_number": { "type": "string", "example": "+919812345678" }, "document": { "type": "string", "example": "ABCDE1234F" }, "country": { "description": "The two-letter country code.\n- **IN:** India.\n", "type": "string", "example": "in", "enum": [ "in" ] }, "payment_type_code": { "description": "Value must be creditcard for card payments.", "type": "string", "example": "creditcard", "enum": [ "creditcard", "mastercard", "rupay", "visa" ] }, "currency_code": { "type": "string", "example": "INR", "enum": [ "INR" ] } } } ] }, "lrs-travel": { "x-schema-group": "Requests", "title": "India LRS Travel Payment Request", "description": "A JSON object that represents an LRS Travel payment: an outward remittance under the Liberalised\nRemittance Scheme, paid by the payer on a hosted page where UPI and cards are available.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "LRS Travel Extra Fields", "required": [ "metadata" ], "properties": { "phone_number": { "type": "string", "description": "Customer phone number, used to identify the payer on the LRS journey.\n", "example": "+919812345678" }, "country": { "description": "The two-letter country code.\n- **IN:** India.\n", "type": "string", "example": "in", "enum": [ "in" ] }, "payment_type_code": { "type": "string", "example": "lrs-travel", "enum": [ "lrs-travel" ] }, "expiration_time_in_seconds": { "type": "integer", "example": 1800, "description": "How long, in seconds, the payer has to complete the payment on the hosted page.\nAccepted values range from 1200 (20 minutes) to 3600 (60 minutes); the minimum, and default,\nis 1200 seconds (20 minutes). When the field is absent, is not an integer or is out of range,\nthe payment is not declined and the default of 1200 seconds (20 minutes) is used instead.\nThe transaction itself stays pending for longer than this window, while EBANX confirms the\nfinal status with the provider, before being cancelled.\n" }, "currency_code": { "type": "string", "example": "INR", "enum": [ "INR" ] }, "metadata": { "type": "object", "title": "Metadata", "description": "Metadata object containing additional payment configuration.", "required": [ "lrs_type" ], "properties": { "lrs_type": { "type": "string", "description": "The kind of travel service being remitted.\n- **flight:** air tickets.\n- **hotel:** accommodation.\n- **tour:** travel packages and tours.\n", "example": "flight", "enum": [ "flight", "hotel", "tour" ] } } } } } ] }, "enrollment-with-notify-hash": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment with Customer Notify Hash", "description": "Enrollment data for payment methods that use pre-charge customer notification\n(notify-then-charge flow). Used by India Card recurring payments.\nThe customer_notify_hash identifies the customer for notification purposes.\nUPI Autopay uses enrollment-with-upi.yaml which extends this schema.\n", "allOf": [ { "$ref": "#/components/schemas/direct-enrollment" }, { "type": "object", "title": "Enrollment With Notify Hash Extra Fields", "properties": { "customer_notify_hash": { "type": "string", "description": "Hash used to identify the customer for pre-charge notification purposes.\nRequired when using the notify-then-charge flow.\n", "example": "notify_hash_abc123" } } } ] }, "upi": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment UPI", "description": "UPI mandate data for UPI Autopay enrollment. Shared between ws/direct (enrollment+charge)\nand ws/userenrollment (standalone enrollment). `vpa` is mandatory for UPI Autopay enrollment.\nNote: `app_links` is response-only data (returned as `payment.upi.app_links`) and is not part\nof the enrollment request.\n", "required": [ "vpa" ], "properties": { "vpa": { "type": "string", "description": "Customer's UPI Virtual Payment Address (VPA).", "example": "customer@upi" } } }, "enrollment-with-upi": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment with UPI", "description": "Enrollment data for UPI Autopay payments. Extends the notify-hash enrollment\nwith the UPI mandate fields (VPA).\n", "allOf": [ { "$ref": "#/components/schemas/enrollment-with-notify-hash" }, { "$ref": "#/components/schemas/enrollment-contact-fields" }, { "type": "object", "title": "Enrollment With UPI Extra Fields", "properties": { "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2). India for UPI Autopay.", "example": "in" }, "subscription": { "allOf": [ { "$ref": "#/components/schemas/subscription" }, { "required": [ "subscription_name", "frequency" ] } ] }, "upi": { "x-conditional": "Required (`upi.vpa`) for upi-collect-autopay when creating an enrollment. Not required for UPI Intent/QR autopay, nor when charging against an existing enrollment.", "$ref": "#/components/schemas/upi" } } } ] }, "upi-autopay": { "x-schema-group": "Requests", "title": "India UPI Autopay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "UPI Autopay Extra Fields", "properties": { "zipcode": { "description": "Customer zip code.", "type": "string", "example": "400001" }, "address": { "type": "string", "example": "123 MG Road" }, "city": { "type": "string", "example": "Mumbai" }, "state": { "type": "string", "example": "MH" }, "phone_number": { "type": "string", "example": "+919812345678" }, "document": { "type": "string", "example": "ABCDE1234F" }, "country": { "description": "The two-letter country code.\n- **IN:** India.\n", "type": "string", "example": "in", "enum": [ "in" ] }, "payment_type_code": { "type": "string", "example": "upi-collect-autopay", "enum": [ "upi-collect-autopay", "upi-intent-autopay", "upi-qrcode-autopay" ] }, "currency_code": { "type": "string", "example": "INR", "enum": [ "INR" ] }, "enrollment": { "$ref": "#/components/schemas/enrollment-with-upi" } } } ] }, "upi-2": { "x-schema-group": "Requests", "title": "India UPI Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "UPI Extra Fields", "properties": { "zipcode": { "description": "Customer zip code.", "type": "string", "example": "400001" }, "address": { "type": "string", "example": "123 MG Road" }, "city": { "type": "string", "example": "Mumbai" }, "state": { "type": "string", "example": "MH" }, "phone_number": { "type": "string", "example": "+919812345678" }, "document": { "type": "string", "example": "ABCDE1234F" }, "country": { "description": "The two-letter country code.\n- **IN:** India.\n", "type": "string", "example": "in", "enum": [ "in" ] }, "payment_type_code": { "type": "string", "example": "upi-qrcode", "enum": [ "upi-intent", "upi-qrcode" ] }, "currency_code": { "type": "string", "example": "INR", "enum": [ "INR" ] } } } ] }, "payment-13": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇮🇳 India", "oneOf": [ { "$ref": "#/components/schemas/card-9" }, { "$ref": "#/components/schemas/lrs-travel" }, { "$ref": "#/components/schemas/upi-autopay" }, { "$ref": "#/components/schemas/upi-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "creditcard": "#/components/schemas/card-9", "mastercard": "#/components/schemas/card-9", "rupay": "#/components/schemas/card-9", "visa": "#/components/schemas/card-9", "lrs-travel": "#/components/schemas/lrs-travel", "upi-collect-autopay": "#/components/schemas/upi-autopay", "upi-intent": "#/components/schemas/upi-2", "upi-intent-autopay": "#/components/schemas/upi-autopay", "upi-qrcode": "#/components/schemas/upi-2", "upi-qrcode-autopay": "#/components/schemas/upi-autopay" } }, "x-conditional-schemas": { "card-recurring": { "description": "Card recurring payments use the same payment_type_code values as one-time card\npayments (creditcard, visa, mastercard, rupay) but are distinguished by the\npresence of the `enrollment` field with `customer_notify_hash`.\n", "x-schema-group": "Requests", "title": "India Card Recurring Payment Request", "allOf": [ { "$ref": "../../shared/payment-request-base.yaml" }, { "type": "object", "title": "Card Recurring Extra Fields", "required": [ "enrollment" ], "properties": { "zipcode": { "description": "Customer zip code.", "type": "string", "example": "400001" }, "address": { "type": "string", "example": "123 MG Road" }, "city": { "type": "string", "example": "Mumbai" }, "state": { "type": "string", "example": "MH" }, "phone_number": { "type": "string", "example": "+919812345678" }, "document": { "type": "string", "example": "ABCDE1234F" }, "country": { "description": "The two-letter country code.\n- **IN:** India.\n", "type": "string", "example": "in", "enum": [ "in" ] }, "payment_type_code": { "description": "Value must be creditcard for card recurring payments.", "type": "string", "example": "creditcard", "enum": [ "creditcard", "mastercard", "rupay", "visa" ] }, "currency_code": { "type": "string", "example": "INR", "enum": [ "INR" ] }, "enrollment": { "$ref": "../../shared/enrollment/enrollment-with-notify-hash.yaml" } } } ] } } }, "airtel": { "x-schema-group": "Requests", "title": "Kenya Airtel Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "Airtel Extra Fields", "properties": { "country": { "description": "The two-letter country code.", "type": "string", "example": "ke", "enum": [ "ke" ] }, "payment_type_code": { "description": "Value must be airtel for Airtel payments.", "type": "string", "example": "airtel", "enum": [ "airtel" ] }, "currency_code": { "type": "string", "example": "KES", "enum": [ "KES", "USD" ] }, "address": { "type": "string", "example": "123 Kenyatta Ave" }, "zipcode": { "type": "string", "example": "00100" }, "city": { "type": "string", "example": "Nairobi" }, "state": { "type": "string", "example": "Nairobi" }, "phone_number": { "type": "string", "example": "+254712345678" }, "document": { "type": "string", "example": "12345678" } } } ] }, "equitel": { "x-schema-group": "Requests", "title": "Kenya Equitel Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "Equitel Extra Fields", "properties": { "country": { "description": "The two-letter country code.", "type": "string", "example": "ke", "enum": [ "ke" ] }, "payment_type_code": { "description": "Value must be equitel for Equitel payments.", "type": "string", "example": "equitel", "enum": [ "equitel" ] }, "currency_code": { "type": "string", "example": "KES", "enum": [ "KES", "USD" ] }, "address": { "type": "string", "example": "123 Kenyatta Ave" }, "zipcode": { "type": "string", "example": "00100" }, "city": { "type": "string", "example": "Nairobi" }, "state": { "type": "string", "example": "Nairobi" }, "phone_number": { "type": "string", "example": "+254712345678" }, "document": { "type": "string", "example": "12345678" } } } ] }, "mobile-money-m-pesa": { "x-schema-group": "Requests", "title": "Kenya M-Pesa Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "type": "object", "title": "Mobile Money M Pesa Extra Fields", "properties": { "country": { "description": "The two-letter country code.", "type": "string", "example": "ke", "enum": [ "ke" ] }, "payment_type_code": { "description": "Value must be mpesa for M-Pesa payments.", "type": "string", "example": "mpesa", "enum": [ "mpesa" ] }, "currency_code": { "type": "string", "example": "KES", "enum": [ "KES", "USD" ] }, "address": { "type": "string", "example": "123 Kenyatta Ave" }, "zipcode": { "type": "string", "example": "00100" }, "city": { "type": "string", "example": "Nairobi" }, "state": { "type": "string", "example": "Nairobi" }, "phone_number": { "type": "string", "example": "+254712345678" }, "document": { "type": "string", "example": "12345678" } } } ] }, "payment-14": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇰🇪 Kenya", "oneOf": [ { "$ref": "#/components/schemas/airtel" }, { "$ref": "#/components/schemas/equitel" }, { "$ref": "#/components/schemas/mobile-money-m-pesa" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "airtel": "#/components/schemas/airtel", "equitel": "#/components/schemas/equitel", "mpesa": "#/components/schemas/mobile-money-m-pesa" } } }, "mx-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Mexico Request Base", "properties": { "country": { "type": "string", "example": "mx", "enum": [ "mx" ] }, "document": { "description": "Customer's document number (RFC or CURP).\n", "type": "string", "example": "XAXX010101000" }, "currency_code": { "type": "string", "example": "MXN", "enum": [ "MXN", "USD" ] }, "state": { "type": "string", "example": "CDMX" }, "phone_number": { "type": "string", "example": "+5215512345678" }, "address": { "type": "string", "example": "Calle Reforma 222" }, "zipcode": { "type": "string", "example": "11000" }, "city": { "type": "string", "example": "Ciudad de México" } } }, "card-10": { "x-schema-group": "Requests", "title": "Mexico Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "carnet", "creditcard", "debitcard", "mastercard", "visa" ] } } } ] }, "aplazo": { "x-schema-group": "Requests", "title": "Mexico Aplazo Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "type": "object", "title": "Aplazo Extra Fields", "properties": { "payment_type_code": { "description": "Value must be aplazo for Aplazo payments.", "type": "string", "example": "aplazo", "enum": [ "aplazo" ] }, "document": { "description": "Customer Document.", "type": "string", "example": "12351346801", "minLength": 1, "maxLength": 16 }, "address": { "description": "Customer Address.", "type": "string", "example": "Av. Reforma 123" }, "street_number": { "description": "Customer Street Number.", "type": "string", "example": "123" }, "zipcode": { "description": "Customer Zip Code.", "type": "string", "example": "11000" }, "city": { "description": "Customer City.", "type": "string", "example": "Ciudad de México" }, "state": { "description": "Customer State / Region / Province.", "type": "string", "example": "CDMX", "minLength": 0, "maxLength": 5 }, "due_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "description": "Payment expiry date.\n", "example": "31/12/2027" }, "operation": { "type": "string", "description": "The operation type.\n", "example": "request" } } } ] }, "directdebit-3": { "x-hidden": true, "x-schema-group": "Requests", "title": "Mexico Direct Debit Payment Request", "description": "Direct debit payment request for Mexico. Requires bank account information\nfor debiting the customer's bank account.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "type": "object", "title": "Directdebit Extra Fields", "properties": { "payment_type_code": { "description": "Value must be directdebit for Direct Debit payments.", "type": "string", "example": "directdebit", "enum": [ "directdebit" ] }, "directdebit": { "$ref": "#/components/schemas/directdebit" } } } ] }, "mercadopago-4": { "x-schema-group": "Requests", "title": "Mexico Mercado Pago Wallet Payment Request", "description": "Mercado Pago Wallet payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "$ref": "#/components/schemas/mercadopago-request-base" } ] }, "mpconnect-4": { "x-schema-group": "Requests", "title": "Mexico Mercado Pago Connect Payment Request", "description": "Mercado Pago Connect recurring payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "$ref": "#/components/schemas/mpconnect-request-base" } ] }, "oxxo-pay": { "x-schema-group": "Requests", "title": "Mexico OXXO Pay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "type": "object", "title": "OXXO Pay Extra Fields", "properties": { "payment_type_code": { "description": "Payment type code for OXXO payments. Accepts both legacy \"oxxo\" and normalized \"oxxopay\".", "type": "string", "example": "oxxopay", "enum": [ "oxxo", "oxxopay" ] } } } ] }, "paynet": { "x-schema-group": "Requests", "title": "Mexico Paynet Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "type": "object", "title": "Paynet Extra Fields", "properties": { "birth_date": { "allOf": [ { "$ref": "#/components/schemas/date-dmy" } ], "description": "Customer's date of birth.\n", "example": "15/03/1990" }, "payment_type_code": { "description": "The value must be \"paynet\" for Paynet payments.", "type": "string", "example": "paynet", "enum": [ "paynet" ] } } } ] }, "spei": { "x-schema-group": "Requests", "title": "Mexico SPEI Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "type": "object", "title": "SPEI Extra Fields", "properties": { "payment_type_code": { "description": "Value must be spei for SPEI payments.", "type": "string", "example": "spei", "enum": [ "spei" ] } } } ] }, "stablecoin-4": { "x-schema-group": "Requests", "title": "Mexico Stablecoin Payment Request", "description": "Stablecoin payment request. This is a multi-country payment method —\nthe same integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/mx-request-base" }, { "$ref": "#/components/schemas/stablecoin-request-base" } ] }, "payment-15": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇲🇽 Mexico", "oneOf": [ { "$ref": "#/components/schemas/card-10" }, { "$ref": "#/components/schemas/aplazo" }, { "$ref": "#/components/schemas/directdebit-3" }, { "$ref": "#/components/schemas/mercadopago-4" }, { "$ref": "#/components/schemas/mpconnect-4" }, { "$ref": "#/components/schemas/oxxo-pay" }, { "$ref": "#/components/schemas/paynet" }, { "$ref": "#/components/schemas/spei" }, { "$ref": "#/components/schemas/stablecoin-4" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-10", "carnet": "#/components/schemas/card-10", "creditcard": "#/components/schemas/card-10", "debitcard": "#/components/schemas/card-10", "mastercard": "#/components/schemas/card-10", "visa": "#/components/schemas/card-10", "aplazo": "#/components/schemas/aplazo", "directdebit": "#/components/schemas/directdebit-3", "mercadopago": "#/components/schemas/mercadopago-4", "mpconnect": "#/components/schemas/mpconnect-4", "mpcredito": "#/components/schemas/mercadopago-4", "oxxo": "#/components/schemas/oxxo-pay", "oxxopay": "#/components/schemas/oxxo-pay", "paynet": "#/components/schemas/paynet", "spei": "#/components/schemas/spei", "usdc": "#/components/schemas/stablecoin-4", "usdt": "#/components/schemas/stablecoin-4" } } }, "ng-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Nigeria Request Base", "properties": { "country": { "type": "string", "example": "ng", "enum": [ "ng" ] }, "currency_code": { "type": "string", "example": "NGN", "enum": [ "NGN", "USD" ] }, "address": { "type": "string", "example": "123 Broad Street" }, "zipcode": { "type": "string", "example": "100001" }, "city": { "type": "string", "example": "Lagos" }, "state": { "type": "string", "example": "Lagos" }, "phone_number": { "type": "string", "example": "+2348012345678" }, "document": { "type": "string", "example": "12345678901" } } }, "bank-transfer-2": { "x-schema-group": "Requests", "title": "Nigeria Bank Transfer Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ng-request-base" }, { "type": "object", "title": "Bank Transfer Extra Fields", "properties": { "payment_type_code": { "description": "Value must be banktransfer for BankTransfer payments.", "type": "string", "example": "banktransfer", "enum": [ "banktransfer" ] }, "bank_details": { "$ref": "#/components/schemas/bank-details" } } } ] }, "card-11": { "x-schema-group": "Requests", "title": "Nigeria Card Payment Request", "description": "Card payment request for Nigeria.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ng-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "description": "Value must be a card type for card payments.", "type": "string", "example": "visa", "enum": [ "creditcard", "debitcard", "mastercard", "visa" ] } } } ] }, "direct-debit-account-details": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Nigeria Direct Debit Account Details", "description": "Nigerian bank account used by the selected direct debit provider.", "required": [ "customer_account_number", "customer_account_bank_code" ], "properties": { "customer_account_number": { "type": "string", "minLength": 1, "description": "Payer bank account number. Send it as a string to preserve leading zeros.", "example": "0051762787" }, "customer_account_bank_code": { "type": "string", "minLength": 1, "description": "Nigerian bank code of the payer bank account.", "example": "044" } } }, "direct-debit-subscription": { "x-hidden": true, "x-schema-group": "Shared", "title": "Nigeria Direct Debit Subscription", "description": "Subscription terms for Nigerian mandates. The subscription name is optional; the selected provider uses a default mandate description when it is omitted.", "allOf": [ { "$ref": "#/components/schemas/subscription" }, { "type": "object", "title": "Nigeria Direct Debit Subscription Fields", "required": [ "expiration_date", "frequency", "start_date" ], "properties": { "expiration_date": { "type": "string", "format": "date", "description": "Mandate expiration date.", "example": "2026-11-09" }, "frequency": { "type": "string", "description": "Selects a single-use mandate with onetime or a recurring mandate with another supported frequency.", "example": "onetime" }, "start_date": { "type": "string", "format": "date", "description": "Mandate start date.", "example": "2026-10-10" } } } ] }, "enrollment-new-mandate": { "x-hidden": true, "type": "object", "title": "Nigeria Direct Debit New Mandate", "additionalProperties": true, "required": [ "direct_debit", "subscription" ], "properties": { "direct_debit": { "$ref": "#/components/schemas/direct-debit-account-details" }, "subscription": { "$ref": "#/components/schemas/direct-debit-subscription" } } }, "enrollment-existing-mandate": { "x-hidden": true, "type": "object", "title": "Nigeria Direct Debit Existing Mandate", "additionalProperties": true, "required": [ "merchant_enrollment_code" ], "properties": { "merchant_enrollment_code": { "type": "string", "maxLength": 250, "description": "Merchant's code identifying the persisted recurring enrollment.", "example": "my-enrollment-code-123" }, "direct_debit": { "type": "object", "title": "Nigeria Direct Debit Existing Mandate Account Restriction", "not": {} }, "subscription": { "type": "object", "title": "Nigeria Direct Debit Existing Mandate Subscription Restriction", "not": {} } } }, "direct-debit": { "x-schema-group": "Requests", "title": "Nigeria Direct Debit Payment Request", "description": "Direct debit payment in Nigeria through the provider selected by the merchant's payment\ntype profile. A new mandate uses enrollment.direct_debit for the payer bank account.\nSubscription frequency onetime creates a single-use mandate; other supported frequencies\ncreate recurring mandates. Subsequent recurring charges reference the persisted enrollment\nthrough merchant_enrollment_code. Hosted checkout only creates fresh one-time mandates.\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ng-request-base" }, { "type": "object", "title": "Nigeria Direct Debit Payment Fields", "properties": { "payment_type_code": { "type": "string", "enum": [ "direct-debit" ], "example": "direct-debit", "description": "Generic direct debit payment method code." }, "enrollment": { "allOf": [ { "$ref": "#/components/schemas/direct-enrollment" }, { "$ref": "#/components/schemas/enrollment-customer-fields" }, { "type": "object", "title": "Nigeria Direct Debit Enrollment Fields", "oneOf": [ { "$ref": "#/components/schemas/enrollment-new-mandate" }, { "$ref": "#/components/schemas/enrollment-existing-mandate" } ], "properties": { "subscription": { "x-conditional": "Required when creating a new mandate", "allOf": [ { "$ref": "#/components/schemas/direct-debit-subscription" } ] }, "direct_debit": { "x-conditional": "Required when creating a new mandate", "allOf": [ { "$ref": "#/components/schemas/direct-debit-account-details" } ] } } } ] } } } ] }, "nibbs": { "x-schema-group": "Requests", "title": "Nigeria NIBBS Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ng-request-base" }, { "type": "object", "title": "Nibbs Extra Fields", "properties": { "payment_type_code": { "description": "Value must be nibbs for NIBBS payments.", "type": "string", "example": "nibbs", "enum": [ "nibbs" ] }, "bank_details": { "$ref": "#/components/schemas/bank-details" } } } ] }, "opay": { "x-schema-group": "Requests", "title": "Nigeria OPay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ng-request-base" }, { "type": "object", "title": "Opay Extra Fields", "properties": { "payment_type_code": { "description": "Value must be opay for OPay payments.", "type": "string", "example": "opay", "enum": [ "opay" ] } } } ] }, "ussd": { "x-schema-group": "Requests", "title": "Nigeria USSD Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ng-request-base" }, { "type": "object", "title": "USSD Extra Fields", "required": [ "bank_details" ], "properties": { "bank_details": { "type": "object", "title": "Bank Details", "description": "Customer bank account details for USSD payments.", "required": [ "bank_code", "account_number" ], "properties": { "bank_code": { "type": "string", "description": "Bank code for the USSD transaction.\n", "example": "057" }, "account_number": { "type": "string", "description": "Customer's bank account number.\n", "example": "0123456789" } } }, "payment_type_code": { "description": "Value must be ussd for USSD payments.", "type": "string", "example": "ussd", "enum": [ "ussd" ] } } } ] }, "payment-16": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇳🇬 Nigeria", "oneOf": [ { "$ref": "#/components/schemas/bank-transfer-2" }, { "$ref": "#/components/schemas/card-11" }, { "$ref": "#/components/schemas/direct-debit" }, { "$ref": "#/components/schemas/nibbs" }, { "$ref": "#/components/schemas/opay" }, { "$ref": "#/components/schemas/ussd" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "banktransfer": "#/components/schemas/bank-transfer-2", "creditcard": "#/components/schemas/card-11", "debitcard": "#/components/schemas/card-11", "direct-debit": "#/components/schemas/direct-debit", "mastercard": "#/components/schemas/card-11", "nibbs": "#/components/schemas/nibbs", "opay": "#/components/schemas/opay", "ussd": "#/components/schemas/ussd", "visa": "#/components/schemas/card-11" } } }, "pa-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Panama Request Base", "properties": { "document": { "description": "Customer's cédula de identidad personal number.\n", "type": "string", "example": "8-888-8888" }, "country": { "type": "string", "example": "pa", "enum": [ "pa" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "PAB", "USD" ] }, "address": { "type": "string", "example": "Calle 50, Edificio Global" }, "zipcode": { "type": "string", "example": "0816" }, "city": { "type": "string", "example": "Ciudad de Panamá" }, "state": { "type": "string", "example": "PA" }, "phone_number": { "type": "string", "example": "+50712345678" } } }, "card-12": { "x-schema-group": "Requests", "title": "Panama Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/pa-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "mastercard", "visa" ] }, "currency_code": { "enum": [ "PAB", "USD" ] } } } ] }, "payment-17": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇵🇦 Panama", "oneOf": [ { "$ref": "#/components/schemas/card-12" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-12", "creditcard": "#/components/schemas/card-12", "debitcard": "#/components/schemas/card-12", "mastercard": "#/components/schemas/card-12", "visa": "#/components/schemas/card-12" } } }, "pe-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Peru Request Base", "properties": { "country": { "type": "string", "example": "pe", "enum": [ "pe" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "PEN", "USD" ] }, "address": { "type": "string", "example": "Av. Arequipa 1234" }, "zipcode": { "type": "string", "example": "15001" }, "city": { "type": "string", "example": "Lima" }, "state": { "type": "string", "example": "LIM" }, "phone_number": { "type": "string", "example": "+51912345678" }, "document": { "type": "string", "example": "09876543" } } }, "card-13": { "x-schema-group": "Requests", "title": "Peru Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/pe-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "diners", "mastercard", "visa" ] }, "instalments": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 48 }, { "type": "string", "pattern": "^\\d+-\\d+$" } ], "description": "The number of instalments of the amount (from 1 to 48, depending on merchant contract).\n", "example": 3 } } } ] }, "pago-efectivo": { "x-schema-group": "Requests", "title": "Peru PagoEfectivo Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/pe-request-base" }, { "type": "object", "title": "PagoEfectivo Extra Fields", "properties": { "payment_type_code": { "description": "Value must be pagoefectivo for PagoEfectivo payments.", "type": "string", "example": "pagoefectivo", "enum": [ "pagoefectivo" ] }, "currency_code": { "type": "string", "example": "PEN" } } } ] }, "safety-pay-2": { "x-schema-group": "Requests", "title": "Peru SafetyPay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/pe-request-base" }, { "type": "object", "title": "Safety Pay Extra Fields", "properties": { "payment_type_code": { "description": "The payment method chosen by the customer.\n", "type": "string", "example": "safetypay-cash", "enum": [ "safetypay-cash", "safetypay-online" ] }, "currency_code": { "type": "string", "example": "PEN" } } } ] }, "stablecoin-5": { "x-schema-group": "Requests", "title": "Peru Stablecoin Payment Request", "description": "Stablecoin payment request. This is a multi-country payment method —\nthe same integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/pe-request-base" }, { "$ref": "#/components/schemas/stablecoin-request-base" } ] }, "yape": { "x-schema-group": "Requests", "title": "Peru Yape Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/pe-request-base" }, { "type": "object", "title": "Yape Extra Fields", "properties": { "payment_type_code": { "description": "Value must be yape for Yape one-shot payments.", "type": "string", "example": "yape", "enum": [ "yape" ] }, "currency_code": { "type": "string", "example": "PEN" } } } ] }, "yape-recurring": { "x-schema-group": "Requests", "title": "Peru Yape Recurring Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/pe-request-base" }, { "type": "object", "title": "Yape Recurring Extra Fields", "properties": { "payment_type_code": { "description": "Value must be yape-recurrent for Yape Recurring payments.", "type": "string", "example": "yape-recurrent", "enum": [ "yape-recurrent" ] }, "currency_code": { "type": "string", "example": "PEN" } } } ] }, "payment-18": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇵🇪 Peru", "oneOf": [ { "$ref": "#/components/schemas/card-13" }, { "$ref": "#/components/schemas/pago-efectivo" }, { "$ref": "#/components/schemas/safety-pay-2" }, { "$ref": "#/components/schemas/stablecoin-5" }, { "$ref": "#/components/schemas/yape-recurring" }, { "$ref": "#/components/schemas/yape" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-13", "creditcard": "#/components/schemas/card-13", "debitcard": "#/components/schemas/card-13", "diners": "#/components/schemas/card-13", "mastercard": "#/components/schemas/card-13", "visa": "#/components/schemas/card-13", "pagoefectivo": "#/components/schemas/pago-efectivo", "safetypay-cash": "#/components/schemas/safety-pay-2", "safetypay-online": "#/components/schemas/safety-pay-2", "usdc": "#/components/schemas/stablecoin-5", "usdt": "#/components/schemas/stablecoin-5", "yape": "#/components/schemas/yape", "yape-recurrent": "#/components/schemas/yape-recurring" } } }, "ph-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Philippines Request Base", "properties": { "country": { "type": "string", "example": "ph", "enum": [ "ph" ] }, "currency_code": { "type": "string", "example": "PHP", "enum": [ "PHP", "USD" ] }, "address": { "type": "string", "example": "123 Rizal Avenue" }, "zipcode": { "type": "string", "example": "1000" }, "city": { "type": "string", "example": "Manila" }, "state": { "type": "string", "example": "NCR" }, "phone_number": { "type": "string", "example": "+639171234567" }, "document": { "type": "string", "example": "1234-5678-9012" } } }, "g-cash": { "x-schema-group": "Requests", "title": "Philippines GCash Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ph-request-base" }, { "type": "object", "title": "GCash Extra Fields", "properties": { "payment_type_code": { "description": "Value must be g-cash for GCash payments.", "type": "string", "example": "g-cash", "enum": [ "g-cash" ] } } } ] }, "maya": { "x-schema-group": "Requests", "title": "Philippines Maya Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ph-request-base" }, { "type": "object", "title": "Maya Extra Fields", "properties": { "payment_type_code": { "description": "Value must be paymaya for Maya payments.", "type": "string", "example": "paymaya", "enum": [ "paymaya" ] } } } ] }, "qrph": { "x-schema-group": "Requests", "title": "Philippines QRPH Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/ph-request-base" }, { "type": "object", "title": "QR Ph Extra Fields", "properties": { "payment_type_code": { "description": "Value must be qrph for QRPH payments.", "type": "string", "example": "qrph", "enum": [ "qrph" ] } } } ] }, "payment-19": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇵🇭 Philippines", "oneOf": [ { "$ref": "#/components/schemas/g-cash" }, { "$ref": "#/components/schemas/maya" }, { "$ref": "#/components/schemas/qrph" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "g-cash": "#/components/schemas/g-cash", "paymaya": "#/components/schemas/maya", "qrph": "#/components/schemas/qrph" } } }, "py-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Paraguay Request Base", "properties": { "document": { "description": "Customer's CI (Cédula de Identidad) number.\n", "type": "string", "example": "1234567" }, "country": { "type": "string", "example": "py", "enum": [ "py" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "PYG", "USD" ] }, "address": { "type": "string", "example": "Av. Mariscal López 3456" }, "zipcode": { "type": "string", "example": "1209" }, "city": { "type": "string", "example": "Asunción" }, "state": { "type": "string", "example": "ASU" }, "phone_number": { "type": "string", "example": "+595212345678" } } }, "card-14": { "x-schema-group": "Requests", "title": "Paraguay Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/py-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "infonet", "mastercard", "visa" ] }, "currency_code": { "enum": [ "PYG", "USD" ] } } } ] }, "payment-20": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇵🇾 Paraguay", "oneOf": [ { "$ref": "#/components/schemas/card-14" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-14", "creditcard": "#/components/schemas/card-14", "debitcard": "#/components/schemas/card-14", "infonet": "#/components/schemas/card-14", "mastercard": "#/components/schemas/card-14", "visa": "#/components/schemas/card-14" } } }, "sv-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "El Salvador Request Base", "properties": { "document": { "description": "Customer's DUI (Documento Único de Identidad) number.\n", "type": "string", "example": "012345678" }, "country": { "type": "string", "example": "sv", "enum": [ "sv" ] }, "currency_code": { "type": "string", "example": "USD", "enum": [ "USD" ] }, "address": { "type": "string", "example": "Boulevard de los Héroes 100" }, "zipcode": { "type": "string", "example": "01101" }, "city": { "type": "string", "example": "San Salvador" }, "state": { "type": "string", "example": "SS" }, "phone_number": { "type": "string", "example": "+50312345678" } } }, "card-15": { "x-schema-group": "Requests", "title": "El Salvador Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/sv-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "debitcard", "mastercard", "visa" ] }, "currency_code": { "enum": [ "USD" ] } } } ] }, "payment-21": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇸🇻 El Salvador", "oneOf": [ { "$ref": "#/components/schemas/card-15" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-15", "creditcard": "#/components/schemas/card-15", "debitcard": "#/components/schemas/card-15", "mastercard": "#/components/schemas/card-15", "visa": "#/components/schemas/card-15" } } }, "th-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Thailand Request Base", "properties": { "country": { "type": "string", "example": "th", "enum": [ "th" ] }, "currency_code": { "type": "string", "example": "THB", "enum": [ "THB" ] }, "phone_number": { "type": "string", "example": "+66812345678" } } }, "mobile-banking": { "x-schema-group": "Requests", "title": "Thailand Mobile Banking Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/th-request-base" }, { "type": "object", "title": "Mobile Banking Extra Fields", "required": [ "bank_details", "redirect_url" ], "properties": { "payment_type_code": { "description": "Value must be mobile-banking for Mobile Banking payments.", "type": "string", "example": "mobile-banking", "enum": [ "mobile-banking" ] }, "bank_details": { "type": "object", "title": "Bank Details", "description": "Bank selected by the customer to complete the payment in the bank's mobile app.", "required": [ "bank_code" ], "properties": { "bank_code": { "type": "string", "description": "Code of the bank selected by the customer:\n`bbl` (Bangkok Bank), `bay` (Krungsri), `kbank` (Kasikorn Bank), `ktb` (Krung Thai) or `scb` (Siam Commercial Bank).\n", "example": "kbank", "enum": [ "bay", "bbl", "kbank", "ktb", "scb" ] } } }, "redirect_url": { "type": "string", "description": "URL the customer is redirected to after completing the payment.", "example": "https://merchant.example.com/callback" } } } ] }, "promptpay": { "x-schema-group": "Requests", "title": "Thailand PromptPay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/th-request-base" }, { "type": "object", "title": "PromptPay Extra Fields", "properties": { "payment_type_code": { "description": "Value must be promptpay for PromptPay payments.", "type": "string", "example": "promptpay", "enum": [ "promptpay" ] } } } ] }, "payment-22": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇹🇭 Thailand", "oneOf": [ { "$ref": "#/components/schemas/mobile-banking" }, { "$ref": "#/components/schemas/promptpay" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "mobile-banking": "#/components/schemas/mobile-banking", "promptpay": "#/components/schemas/promptpay" } } }, "tr-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Turkey Request Base", "required": [ "document", "phone_number", "address", "city", "zipcode" ], "properties": { "country": { "type": "string", "example": "tr", "enum": [ "tr" ] }, "currency_code": { "type": "string", "example": "TRY", "enum": [ "TRY" ] }, "document": { "type": "string", "description": "Customer's identity number (T.C. Kimlik No).\n", "example": "10000000146" }, "phone_number": { "type": "string", "example": "5321234567" }, "address": { "type": "string", "example": "Istiklal Caddesi 123" }, "city": { "type": "string", "example": "Istanbul" }, "zipcode": { "type": "string", "example": "34430" } } }, "bank-transfer-3": { "x-schema-group": "Requests", "title": "Turkey Bank Transfer Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/tr-request-base" }, { "type": "object", "title": "Bank Transfer Extra Fields", "properties": { "payment_type_code": { "description": "Value must be banktransfer for Bank Transfer payments.", "type": "string", "example": "banktransfer", "enum": [ "banktransfer" ] } } } ] }, "payment-23": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇹🇷 Turkey", "oneOf": [ { "$ref": "#/components/schemas/bank-transfer-3" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "banktransfer": "#/components/schemas/bank-transfer-3" } } }, "uy-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Uruguay Request Base", "properties": { "document": { "description": "Customer's CI (Cédula de Identidad) number.\n", "type": "string", "example": "9.999.999-9" }, "country": { "type": "string", "example": "uy", "enum": [ "uy" ] }, "currency_code": { "type": "string", "example": "UYU", "enum": [ "USD", "UYU" ] }, "address": { "type": "string", "example": "Av. 18 de Julio 1234" }, "zipcode": { "type": "string", "example": "11000" }, "city": { "type": "string", "example": "Montevideo" }, "state": { "type": "string", "example": "MO" }, "phone_number": { "type": "string", "example": "+598912345678" } } }, "card-16": { "x-schema-group": "Requests", "title": "Uruguay Card Payment Request", "description": "Card payment request (credit card and debit card). This is a multi-country payment method —\nthe same card integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/uy-request-base" }, { "$ref": "#/components/schemas/card-payment-features" }, { "type": "object", "title": "Card Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard", "enum": [ "amex", "creditcard", "creditel", "debitcard", "diners", "lider", "mastercard", "oca", "visa" ] }, "currency_code": { "enum": [ "USD", "UYU" ] } } } ] }, "mercadopago-5": { "x-schema-group": "Requests", "title": "Uruguay Mercado Pago Wallet Payment Request", "description": "Mercado Pago Wallet payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/uy-request-base" }, { "$ref": "#/components/schemas/mercadopago-request-base" } ] }, "mpconnect-5": { "x-schema-group": "Requests", "title": "Uruguay Mercado Pago Connect Payment Request", "description": "Mercado Pago Connect recurring payment request. This is a multi-country payment method —\nthe same integration works across all supported countries (AR, BR, CL, MX, UY)\nwith minimal changes (country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/uy-request-base" }, { "$ref": "#/components/schemas/mpconnect-request-base" } ] }, "stablecoin-6": { "x-schema-group": "Requests", "title": "Uruguay Stablecoin Payment Request", "description": "Stablecoin payment request. This is a multi-country payment method —\nthe same integration works across all supported countries with minimal changes\n(country, currency, and document fields).\n", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/uy-request-base" }, { "$ref": "#/components/schemas/stablecoin-request-base" } ] }, "payment-24": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇺🇾 Uruguay", "oneOf": [ { "$ref": "#/components/schemas/card-16" }, { "$ref": "#/components/schemas/mercadopago-5" }, { "$ref": "#/components/schemas/mpconnect-5" }, { "$ref": "#/components/schemas/stablecoin-6" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-16", "creditcard": "#/components/schemas/card-16", "creditel": "#/components/schemas/card-16", "debitcard": "#/components/schemas/card-16", "diners": "#/components/schemas/card-16", "lider": "#/components/schemas/card-16", "mastercard": "#/components/schemas/card-16", "oca": "#/components/schemas/card-16", "visa": "#/components/schemas/card-16", "mercadopago": "#/components/schemas/mercadopago-5", "mpconnect": "#/components/schemas/mpconnect-5", "mpcredito": "#/components/schemas/mercadopago-5", "usdc": "#/components/schemas/stablecoin-6", "usdt": "#/components/schemas/stablecoin-6" } } }, "za-request-base": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "South Africa Request Base", "properties": { "country": { "type": "string", "example": "za", "enum": [ "za" ] }, "currency_code": { "type": "string", "example": "ZAR", "enum": [ "USD", "ZAR" ] }, "address": { "type": "string", "example": "123 Long Street" }, "zipcode": { "type": "string", "example": "8001" }, "city": { "type": "string", "example": "Cape Town" }, "state": { "type": "string", "example": "WC" }, "phone_number": { "type": "string", "example": "+27821234567" }, "document": { "type": "string", "example": "8001015009086" } } }, "capitec-pay": { "x-schema-group": "Requests", "title": "South Africa Capitec Pay Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/za-request-base" }, { "type": "object", "title": "Capitec Pay Extra Fields", "properties": { "payment_type_code": { "description": "Value must be capitec-pay for CapitecPay payments.", "type": "string", "example": "capitec-pay", "enum": [ "capitec-pay" ] } } } ] }, "mobile-money-m-pesa-2": { "x-schema-group": "Requests", "title": "South Africa M-Pesa Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/za-request-base" }, { "type": "object", "title": "Mobile Money M Pesa Extra Fields", "properties": { "payment_type_code": { "description": "Value must be mpesa for M-Pesa payments.", "type": "string", "example": "mpesa", "enum": [ "mpesa" ] } } } ] }, "ozow": { "x-schema-group": "Requests", "title": "South Africa Ozow Payment Request", "description": "A JSON object that represents the payment.", "allOf": [ { "$ref": "#/components/schemas/payment-request-base" }, { "$ref": "#/components/schemas/za-request-base" }, { "type": "object", "title": "Ozow Extra Fields", "properties": { "redirect_url": { "type": "string", "description": "URL to redirect customer after payment completion.\n", "example": "https://merchant.example.com/callback" }, "payment_type_code": { "description": "Value must be ozow for Ozow payments.", "type": "string", "example": "ozow", "enum": [ "ozow" ] } } } ] }, "payment-25": { "x-hidden": true, "x-schema-group": "Requests", "title": "🇿🇦 South Africa", "oneOf": [ { "$ref": "#/components/schemas/capitec-pay" }, { "$ref": "#/components/schemas/mobile-money-m-pesa-2" }, { "$ref": "#/components/schemas/ozow" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "capitec-pay": "#/components/schemas/capitec-pay", "mpesa": "#/components/schemas/mobile-money-m-pesa-2", "ozow": "#/components/schemas/ozow" } } }, "direct-request": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Direct Payment Request", "required": [ "payment" ], "properties": { "browser_info": { "$ref": "#/components/schemas/browser-info" }, "payment": { "description": "The payment object containing all transaction details. Structure varies by country and payment method.", "x-default-expanded": false, "oneOf": [ { "$ref": "#/components/schemas/payment" }, { "$ref": "#/components/schemas/payment-2" }, { "$ref": "#/components/schemas/payment-3" }, { "$ref": "#/components/schemas/payment-4" }, { "$ref": "#/components/schemas/payment-5" }, { "$ref": "#/components/schemas/payment-6" }, { "$ref": "#/components/schemas/payment-7" }, { "$ref": "#/components/schemas/payment-8" }, { "$ref": "#/components/schemas/payment-9" }, { "$ref": "#/components/schemas/payment-10" }, { "$ref": "#/components/schemas/payment-11" }, { "$ref": "#/components/schemas/payment-12" }, { "$ref": "#/components/schemas/payment-13" }, { "$ref": "#/components/schemas/payment-14" }, { "$ref": "#/components/schemas/payment-15" }, { "$ref": "#/components/schemas/payment-16" }, { "$ref": "#/components/schemas/payment-17" }, { "$ref": "#/components/schemas/payment-18" }, { "$ref": "#/components/schemas/payment-20" }, { "$ref": "#/components/schemas/payment-21" }, { "$ref": "#/components/schemas/payment-19" }, { "$ref": "#/components/schemas/payment-22" }, { "$ref": "#/components/schemas/payment-23" }, { "$ref": "#/components/schemas/payment-24" }, { "$ref": "#/components/schemas/payment-25" } ], "discriminator": { "propertyName": "country", "mapping": { "ar": "#/components/schemas/payment", "bo": "#/components/schemas/payment-2", "br": "#/components/schemas/payment-3", "cl": "#/components/schemas/payment-4", "co": "#/components/schemas/payment-5", "cr": "#/components/schemas/payment-6", "do": "#/components/schemas/payment-7", "ec": "#/components/schemas/payment-8", "eg": "#/components/schemas/payment-9", "gh": "#/components/schemas/payment-10", "gt": "#/components/schemas/payment-11", "id": "#/components/schemas/payment-12", "in": "#/components/schemas/payment-13", "ke": "#/components/schemas/payment-14", "mx": "#/components/schemas/payment-15", "ng": "#/components/schemas/payment-16", "pa": "#/components/schemas/payment-17", "pe": "#/components/schemas/payment-18", "ph": "#/components/schemas/payment-19", "py": "#/components/schemas/payment-20", "sv": "#/components/schemas/payment-21", "th": "#/components/schemas/payment-22", "tr": "#/components/schemas/payment-23", "uy": "#/components/schemas/payment-24", "za": "#/components/schemas/payment-25" } } } } }, "payment-status": { "title": "Payment Status", "x-schema-group": "Shared", "type": "string", "description": "The payment status.\n", "oneOf": [ { "enum": [ "OP" ], "description": "The customer has not yet filled the payment details on the EBANX Checkout." }, { "enum": [ "PE" ], "description": "The payment is pending confirmation." }, { "enum": [ "CO" ], "description": "The payment is confirmed (paid)." }, { "enum": [ "CA" ], "description": "The payment is cancelled." } ], "example": "CO" }, "nullable-datetime": { "x-hidden": true, "title": "Nullable Datetime", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1]) ([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])$", "description": "Date and time.", "nullable": true }, "sub-account-2": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "nullable": true, "title": "Sub Account Response", "description": "Sub account information for the payment.\n", "properties": { "name": { "type": "string", "description": "Name of the sub account.\n", "example": "My Store" }, "image_url": { "type": "string", "nullable": true, "description": "URL of the logo of the sub account.\n", "example": "https://example.com/logo.png" }, "sub_account_code": { "type": "string", "nullable": true, "description": "The unique code identifier of the sub account.\n", "example": "my-store-001" } } }, "transaction-status-code": { "title": "Transaction Status Codes", "x-schema-group": "Shared", "type": "string", "description": "The transaction status code returned in the payment response.\n", "oneOf": [ { "enum": [ "NOK" ], "description": "The transaction was not accepted." }, { "enum": [ "NO_RETRY" ], "description": "The transaction was not accepted and should not be retried." }, { "enum": [ "OK" ], "description": "The transaction was accepted." }, { "enum": [ "PENDING_AUTHENTICATION" ], "description": "The transaction is pending customer authentication (e.g. 3DS)." }, { "enum": [ "PENDING_CARD_PIN" ], "description": "The transaction is pending card PIN entry." }, { "enum": [ "RETRY" ], "description": "The transaction can be retried." } ], "example": "OK" }, "apm-description-code": { "title": "APM Description Codes", "x-schema-group": "Response Codes", "type": "string", "description": "Transaction status description codes returned for Alternative Payment Method (APM) transactions\nin `payment.transaction_status.description_code`.\nThese codes indicate the result of the payment processing by the provider.\n", "oneOf": [ { "enum": [ "ACCEPTED" ], "description": "Payment successfully paid." }, { "enum": [ "ATTEMPTS_EXCEEDED_MPIN_OR_OTP" ], "description": "Authentication failed due to incorrect input by user." }, { "enum": [ "BIN_MISMATCH" ], "description": "Bin mismatch for UPI on CC transactions." }, { "enum": [ "BROKEN_COMMUNICATION" ], "description": "Broken communication." }, { "enum": [ "CANCELED_BY_MERCHANT" ], "description": "Payment cancellation requested by the merchant." }, { "enum": [ "CANCELED_BY_PAYER" ], "description": "Payment cancellation requested by the user." }, { "enum": [ "CANNOT_TRANSACTION" ], "description": "Cannot process transaction at this moment." }, { "enum": [ "COMMUNICATION_MISMATCH" ], "description": "Communication mismatch." }, { "enum": [ "CUSTOMER_NOT_FOUND" ], "description": "Customer not found at the provider." }, { "enum": [ "CUSTOMER_NUMBER_OR_ACCOUNT_CHANGE" ], "description": "User account has undergone changes to primary values." }, { "enum": [ "DECLINED_BY_CC_ISSUING_BANK" ], "description": "The transaction was declined directly by the card's issuing bank." }, { "enum": [ "DECLINED_DUE_TIMEOUT" ], "description": "Declined due timeout." }, { "enum": [ "DEFAULT_ERROR" ], "description": "Unknown acquirer error." }, { "enum": [ "DEFAULT_REASON" ], "description": "Unknown decline reason." }, { "enum": [ "DO_NOT_HONOUR" ], "description": "Payment rejected by bank due to internal checks." }, { "enum": [ "DUPLICATE_TRANSACTION" ], "description": "Duplicate Mandate/transaction request." }, { "enum": [ "ENROLLMENT_CANCELLED" ], "description": "Enrollment is no longer active." }, { "enum": [ "ENROLLMENT_CONFIRMATION_FAILURE" ], "description": "Issue in enrollment confirmation by user bank." }, { "enum": [ "ENROLLMENT_NOT_ACTIVE" ], "description": "Enrollment is not active." }, { "enum": [ "ENROLLMENT_PAUSED" ], "description": "Enrollment paused by the customer." }, { "enum": [ "EWALLET_INSTANT_RETRY_ERROR" ], "description": "E-wallet instant retry error. Attempt failed, please try again." }, { "enum": [ "EXPIRED_AFTER_3RETRIES" ], "description": "Payment cancelled after 3 retries." }, { "enum": [ "EXPIRED_AFTER_7DAYS" ], "description": "Payment expired after 7 days cap." }, { "enum": [ "EXPIRED_BY_USER_INACTION" ], "description": "Payment expired due to user inaction." }, { "enum": [ "FRAUD_RISK" ], "description": "Transaction declined due to suspected fraud." }, { "enum": [ "HIGH_RISK_TRANSACTION" ], "description": "Transaction declined by the payer bank due to risk restrictions." }, { "enum": [ "INCORRECT_CUSTOMER_DATA" ], "description": "Incorrect customer data." }, { "enum": [ "INCORRECT_ITEMS_DATA" ], "description": "Incorrect or restricted HSN Code." }, { "enum": [ "INSUFFICIENT_FUNDS" ], "description": "Insufficient funds." }, { "enum": [ "INSUFFICIENT_FUNDS_OR_DAILY_LIMIT" ], "description": "Insufficient funds or limit restrictions in the user's account." }, { "enum": [ "INTERNAL_SERVER_ERROR" ], "description": "Internal server error." }, { "enum": [ "INVALID_AMOUNT" ], "description": "Value sent in the amount field is incorrect." }, { "enum": [ "INVALID_CARD" ], "description": "The card is expired, blocked, or not supported for this type of purchase." }, { "enum": [ "INVALID_CARD_DATA" ], "description": "Transaction declined due to incorrect card information entered by the user." }, { "enum": [ "INVALID_DUE_DATE" ], "description": "Invalid due date." }, { "enum": [ "INVALID_MPIN_OR_OTP" ], "description": "Authentication failed due to incorrect input by user." }, { "enum": [ "INVALID_PARAMETERS" ], "description": "Invalid parameters." }, { "enum": [ "INVALID_VPA" ], "description": "VPA is either invalid or is inactive." }, { "enum": [ "LIMIT_EXCEEDED" ], "description": "Payment declined as the amount exceeds the maximum threshold defined by the payer." }, { "enum": [ "MANDATE_EXPIRED" ], "description": "Enrollment has expired." }, { "enum": [ "MANDATE_NOT_FOUND" ], "description": "Enrollment does not exist or is not valid in the network/issuer system." }, { "enum": [ "MANDATE_PAUSED" ], "description": "Enrollment paused by the customer." }, { "enum": [ "MANDATE_REVOKED" ], "description": "Enrollment revoked by the customer." }, { "enum": [ "MAX_AMOUNT_EXCEEDED" ], "description": "Payment declined as the amount exceeds the maximum threshold." }, { "enum": [ "NO_ACCEPTED" ], "description": "Not accepted." }, { "enum": [ "NO_ACCEPTED_RETRYABLE" ], "description": "Not accepted (should be retried)." }, { "enum": [ "NO_ACTION_BY_PAYER" ], "description": "Authentication not completed by user." }, { "enum": [ "NOT_ALLOW_RETRY" ], "description": "Liquidation failed and retry is not possible." }, { "enum": [ "NOTIFICATION_DELIVERY_FAILED" ], "description": "The notification was sent but failed to be delivered to the customer." }, { "enum": [ "NOTIFICATION_NOT_FOUND" ], "description": "Pre debit notification not sent for the payment." }, { "enum": [ "PAYEE_BLOCKED_AT_REMITTER" ], "description": "Merchant blocked at Remitter Bank due to internal checks." }, { "enum": [ "PAYMENT_NOT_VALID" ], "description": "Invalid payment scheduling." }, { "enum": [ "PROVIDER_RESPONSE_ERROR" ], "description": "Provider response error." }, { "enum": [ "REJECTED_BY_USER" ], "description": "Enrollment rejected by the user." }, { "enum": [ "REMITTER_BANK_NOT_AVAILABLE" ], "description": "Bank doesn't support the payment method." }, { "enum": [ "SUSPECTED_FRAUD_REMITTER_BANK" ], "description": "Payment declined based on risk score by remitter." }, { "enum": [ "TECHNICAL_ERROR" ], "description": "Technical failures or gateway errors." }, { "enum": [ "TIMEOUT" ], "description": "External service not available, try again." }, { "enum": [ "TIMEOUT_ACQUIRING_BANK_UNAVAILABLE" ], "description": "External service not available (acquiring bank), try again." }, { "enum": [ "TIMEOUT_BENEFICIARY_BANK_UNAVAILABLE" ], "description": "External service not available (beneficiary bank), try again." }, { "enum": [ "TIMEOUT_NPCI_UNAVAILABLE" ], "description": "External service not available (NPCI), try again." }, { "enum": [ "TIMEOUT_REMITTER_BANK_UNAVAILABLE" ], "description": "External service not available (remitter bank), try again." }, { "enum": [ "TRANSACTION_NOT_FOUND" ], "description": "Transaction not found." }, { "enum": [ "USER_ACCOUNT_CLOSED" ], "description": "User account is closed or blocked." }, { "enum": [ "USER_BANK_VALIDATION_ISSUE" ], "description": "Something went wrong in user bank data validation." }, { "enum": [ "WRONG_AMOUNT_UNDERPAID" ], "description": "Invalid amount paid (Underpaid)." } ], "example": "ACCEPTED" }, "apm-transaction-status": { "x-schema-group": "Shared", "type": "object", "title": "Transaction Status APM", "description": "A JSON object that represents the APM transaction status.\n", "properties": { "acquirer": { "type": "string", "description": "The acquirer that processed the transaction.\n", "example": "EBANX" }, "code": { "oneOf": [ { "$ref": "#/components/schemas/transaction-status-code" } ], "description": "The transaction status code.\n", "example": "OK" }, "description": { "type": "string", "description": "A human-readable description for the transaction status.\n", "example": "Payment successfully paid" }, "description_code": { "oneOf": [ { "$ref": "#/components/schemas/apm-description-code" } ], "description": "The machine-readable description code for the transaction status.\n", "example": "ACCEPTED" }, "authcode": { "type": "string", "description": "Authorization code returned by the acquirer for this transaction.\n", "example": "ABC123" } } }, "payment-response-base": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Payment Response Base", "description": "Base fields shared across all payment responses.\n", "required": [ "hash", "country", "merchant_payment_code", "status", "status_date", "open_date", "amount_br", "amount_ext", "amount_iof", "currency_rate", "currency_ext", "payment_type_code" ], "properties": { "hash": { "type": "string", "description": "The payment hash (EBANX unique identifier).\n", "example": "6565db1ea54eb7c3b13aa9f44b256f4f6b29b510c29168be", "maxLength": 48 }, "country": { "type": "string", "example": "br", "description": "The two-letter country code. Mirrors the value sent in the request.\n", "minLength": 2, "maxLength": 2 }, "merchant_payment_code": { "type": "string", "description": "The payment hash Merchant Payment Code (unique merchant ID).\n", "example": "merchant-payment-code-123" }, "status": { "oneOf": [ { "$ref": "#/components/schemas/payment-status" } ], "description": "The payment status.\n", "example": "CO" }, "status_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "The date and hour of the last status change (UTC).\nNull when the payment has just been created and no status transition has occurred yet.\n", "example": "2027-06-12 12:30:40" }, "open_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "The date and hour of when the payment was created (UTC).\nNull for freshly-created pending payments before the provider confirms creation.\n", "example": "2027-06-12 12:30:40" }, "confirm_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "The date and hour of when the payment was confirmed (UTC).\n", "example": "2027-06-12 12:30:40" }, "transfer_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "The date and hour of when the payment was settled (UTC).\n", "example": "2027-06-15 10:00:00" }, "amount_br": { "type": "string", "nullable": true, "description": "The amount in local currency.\nNull for pending payments before currency conversion is completed.\n", "example": "99.85" }, "amount_ext": { "type": "string", "nullable": true, "description": "The amount in the original currency.\nNull for pending payments before currency conversion is completed.\n", "example": "99.85" }, "amount_iof": { "type": "string", "nullable": true, "description": "The tax amount in local currency (varies between countries).\nNull for pending payments before processing is completed.\n", "example": "0.00" }, "currency_rate": { "type": "string", "nullable": true, "description": "The exchange rate used in the payment.\nNull for pending payments before the rate is determined.\n", "example": "1.0000" }, "currency_ext": { "type": "string", "nullable": true, "description": "ISO 4217 three letter code of the original currency.\nNull for pending payments before currency conversion.\n", "minLength": 3, "maxLength": 3, "example": "BRL" }, "due_date": { "type": "string", "format": "date", "nullable": true, "description": "Expiry date of the payment.\n", "example": "2027-12-31" }, "instalments": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 48 }, { "type": "string", "pattern": "^\\d+$" } ], "description": "Number of instalments for the payment, default value is 1.\n", "example": 1 }, "payment_type_code": { "type": "string", "description": "The code of the payment method. Note: some codes are normalized in the response (e.g., `safetypay-cash` → `safetypay`, `upi-qrcode` → `upi`, `mpesa` → `mobile-money`).\n", "minLength": 1, "maxLength": 32, "example": "creditcard" }, "pre_approved": { "type": "boolean", "description": "Flag that shows if a payment is pre-approved by the acquirer.\n", "example": true }, "sub_account": { "$ref": "#/components/schemas/sub-account-2" }, "transaction_status": { "$ref": "#/components/schemas/apm-transaction-status" }, "qrcode_url": { "type": "string", "nullable": true, "description": "URL to the QR code image for the payment. Present for payment types that use QR code (e.g., PIX, UPI).\n", "example": "https://sandbox.ebanxpay.com/qrcode/payment-hash" }, "voucher_url": { "type": "string", "description": "URL to the payment voucher/receipt. Present for voucher-based payment methods (e.g. bank transfer, cash).\n", "example": "https://sandbox.ebanxpay.com/voucher" } } }, "card-description-code": { "title": "Card Transaction Description Codes", "x-schema-group": "Response Codes", "type": "string", "description": "Machine-readable description codes returned for card (credit/debit) transactions in\n`payment.transaction_status.description_code`. The value is derived from the acquirer\nresponse code (or `ACCEPTED` when the payment is confirmed), plus card-specific codes\nsuch as `BLOCKED_BY_BRAND_MANDATE`.\n", "oneOf": [ { "enum": [ "3DSECURE_REQUIRED" ], "description": "3-D Secure is enabled for the credit card." }, { "enum": [ "ACCEPTED" ], "description": "The transaction was accepted." }, { "enum": [ "ALREADY_FULLY_REFUNDED" ], "description": "The transaction has already been fully refunded." }, { "enum": [ "AWAITING_DONT_RETRY" ], "description": "The transaction is awaiting processing. Do not retry." }, { "enum": [ "BLOCKED_BY_BRAND_MANDATE" ], "description": "The transaction was blocked by a card brand mandate rule. All acquirer routes were exhausted. Check `brand_mandate` in the transaction status for details and retry timing; do not retry before the `retry_after` timestamp." }, { "enum": [ "BROKEN_COMMUNICATION" ], "description": "The connection was broken at some point. Retry at any time." }, { "enum": [ "CANNOT_CANCEL_TRANSACTION" ], "description": "The transaction could not be cancelled. Do not retry." }, { "enum": [ "CANNOT_TRANSACTION" ], "description": "The acquirer could not process the request at the moment. Retry at any time." }, { "enum": [ "CARD_NOT_ENABLED_FOR_ECOMMERCE" ], "description": "The card is not enabled for e-commerce transactions." }, { "enum": [ "CARD_NUMBER" ], "description": "The credit card number is invalid. Advise the customer to review the credit card data." }, { "enum": [ "CLOSED_ACCOUNT" ], "description": "The associated account is closed." }, { "enum": [ "COMMUNICATION_MISMATCH" ], "description": "Bad communication between EBANX and the acquirer. Retry at any time." }, { "enum": [ "DECLINED_DUE_INVALID_PARAMETERS" ], "description": "Declined due to invalid parameters." }, { "enum": [ "DECLINED_DUE_SCHEME_RULES" ], "description": "Declined due to card scheme rules." }, { "enum": [ "DECLINED_DUE_TIMEOUT" ], "description": "Declined due to a timeout." }, { "enum": [ "DEFAULT_ERROR" ], "description": "A generic processing error occurred." }, { "enum": [ "DUPLICATED_REFUND_REQUEST" ], "description": "A refund request for this transaction already exists." }, { "enum": [ "EXCEEDS_WITHDRAWAL_LIMIT" ], "description": "The transaction exceeds the card withdrawal limit." }, { "enum": [ "EXPIRED_CARD" ], "description": "The card has already expired. Advise the customer to use another credit card." }, { "enum": [ "FAILED_TO_PROCESS" ], "description": "The transaction failed to process." }, { "enum": [ "HIGH_RISK_TRANSACTION" ], "description": "The transaction was declined for having a high probability of being fraudulent." }, { "enum": [ "INACTIVE_CARD" ], "description": "The credit card is not active. Retry at any time." }, { "enum": [ "INCORRECT_CUSTOMER_DATA" ], "description": "The customer data is incorrect. Advise the customer to review their data." }, { "enum": [ "INSTALLMENTS_NOT_AVAILABLE" ], "description": "Installments are not available for this transaction." }, { "enum": [ "INSTALLMENTS_UNSUPPORTED" ], "description": "The selected number of installments is not supported by the card issuer." }, { "enum": [ "INSUFFICIENT_FUNDS" ], "description": "The credit card has no funds at the time of the transaction." }, { "enum": [ "INVALID_CARD_OR_TYPE" ], "description": "The credit card is invalid, nonexistent, or blocked." }, { "enum": [ "INVALID_DUE_DATE" ], "description": "The credit card due date is invalid." }, { "enum": [ "ISSUER_DECLINE" ], "description": "The transaction was declined by the issuing bank." }, { "enum": [ "ISSUER_DECLINE_SUSPECT_FRAUD" ], "description": "The issuing bank declined the transaction due to suspected fraud." }, { "enum": [ "NO_ACCEPTED" ], "description": "The transaction was not approved. Advise the customer to contact the credit card issuer." }, { "enum": [ "NO_ACCEPTED_RETRYABLE" ], "description": "The transaction was not approved but can be retried." }, { "enum": [ "NO_FULFILL" ], "description": "The transaction could not be fulfilled or was already executed. Do not retry." }, { "enum": [ "NO_RESPONSE" ], "description": "The acquirer did not respond to the request. Retry at any time." }, { "enum": [ "PAYMENT_TOO_OLD_TO_REFUND" ], "description": "The payment is too old to be refunded." }, { "enum": [ "PENDING_AUTHENTICATION" ], "description": "The transaction is pending authentication." }, { "enum": [ "PENDING_CARD_PIN" ], "description": "The transaction is pending card PIN entry." }, { "enum": [ "PICKUP_CARD" ], "description": "The card was flagged for pickup by the issuer. Do not retry." }, { "enum": [ "PIN_TRIES_EXCEEDED" ], "description": "The allowed number of PIN attempts was exceeded." }, { "enum": [ "REFUND_AMOUNT_EXCEEDED" ], "description": "The refund amount exceeds the original transaction amount." }, { "enum": [ "REFUND_DECLINED_DUE_ACCOUNT_WITH_ISSUE" ], "description": "Refund declined: account with issue." }, { "enum": [ "REFUND_DECLINED_DUE_AWAITING" ], "description": "Refund declined: awaiting." }, { "enum": [ "REFUND_DECLINED_DUE_BLOCKED_CARD" ], "description": "Refund declined: blocked card." }, { "enum": [ "REFUND_DECLINED_DUE_CANNOT_TRANSACTION_NOW" ], "description": "Refund declined: cannot transaction now." }, { "enum": [ "REFUND_DECLINED_DUE_CARD_WITH_ISSUE" ], "description": "Refund declined: card with issue." }, { "enum": [ "REFUND_DECLINED_DUE_CHARGEBACK_IN_ACQUIRER" ], "description": "Refund declined: chargeback in acquirer." }, { "enum": [ "REFUND_DECLINED_DUE_CHARGEBACK_IN_ANALYSIS" ], "description": "Refund declined: chargeback in analysis." }, { "enum": [ "REFUND_DECLINED_DUE_CLOSED_ACCOUNT" ], "description": "Refund declined: closed account." }, { "enum": [ "REFUND_DECLINED_DUE_COMMUNICATION_ERROR" ], "description": "Refund declined: communication error." }, { "enum": [ "REFUND_DECLINED_DUE_DUPLICATE_RECORDS" ], "description": "Refund declined: duplicate records." }, { "enum": [ "REFUND_DECLINED_DUE_ERROR_UNKNOWN" ], "description": "Refund declined: error unknown." }, { "enum": [ "REFUND_DECLINED_DUE_EXCEEDED_ATTEMPTS" ], "description": "Refund declined: exceeded attempts." }, { "enum": [ "REFUND_DECLINED_DUE_EXPIRED_CARD" ], "description": "Refund declined: expired card." }, { "enum": [ "REFUND_DECLINED_DUE_FOR_FINANCE_MANUAL_HANDLING" ], "description": "Refund declined: for finance manual handling." }, { "enum": [ "REFUND_DECLINED_DUE_FOR_FINANCE_REMITTANCE" ], "description": "Refund declined: for finance remittance." }, { "enum": [ "REFUND_DECLINED_DUE_INSUFFICIENT_FUNDS" ], "description": "Refund declined: insufficient funds." }, { "enum": [ "REFUND_DECLINED_DUE_INVALID_AMOUNT" ], "description": "Refund declined: invalid amount." }, { "enum": [ "REFUND_DECLINED_DUE_INVALID_CARD" ], "description": "Refund declined: invalid card." }, { "enum": [ "REFUND_DECLINED_DUE_INVALID_CURRENCY" ], "description": "Refund declined: invalid currency." }, { "enum": [ "REFUND_DECLINED_DUE_INVALID_FIELD" ], "description": "Refund declined: invalid field." }, { "enum": [ "REFUND_DECLINED_DUE_INVALID_SETTING_IN_ACQUIRER" ], "description": "Refund declined: invalid setting in acquirer." }, { "enum": [ "REFUND_DECLINED_DUE_INVALID_TRANSACTION" ], "description": "Refund declined: invalid transaction." }, { "enum": [ "REFUND_DECLINED_DUE_INVALID_TRANSACTION_RETRYABLE" ], "description": "Refund declined: invalid transaction retryable." }, { "enum": [ "REFUND_DECLINED_DUE_LOCK_ON_ACQUIRER" ], "description": "Refund declined: lock on acquirer." }, { "enum": [ "REFUND_DECLINED_DUE_MISSING_REQUIRED_FIELD" ], "description": "Refund declined: missing required field." }, { "enum": [ "REFUND_DECLINED_DUE_NON_REFUNDABLE_TRANSACTION_TYPE" ], "description": "Refund declined: non refundable transaction type." }, { "enum": [ "REFUND_DECLINED_DUE_OLDER_TOO_OLD" ], "description": "Refund declined: older too old." }, { "enum": [ "REFUND_DECLINED_DUE_PICKUP_CARD" ], "description": "Refund declined: pickup card." }, { "enum": [ "REFUND_DECLINED_DUE_REFUND_ALREADY_EXISTS" ], "description": "Refund declined: refund already exists." }, { "enum": [ "REFUND_DECLINED_DUE_RISK_RULES" ], "description": "Refund declined: risk rules." }, { "enum": [ "REFUND_DECLINED_DUE_SCHEME_RULES" ], "description": "Refund declined: scheme rules." }, { "enum": [ "REFUND_DECLINED_DUE_TRANSACTION_NOT_FOUND" ], "description": "Refund declined: transaction not found." }, { "enum": [ "REFUND_DECLINED_DUE_UNAVAILABLE_OR_ERROR" ], "description": "Refund declined: unavailable or error." }, { "enum": [ "REFUND_DECLINED_DUE_UNSUPPORTED_PAYMENT_TYPE" ], "description": "Refund declined: unsupported payment type." }, { "enum": [ "REFUNDED" ], "description": "A refund has been issued for this credit card. Do not retry." }, { "enum": [ "RESPONSE_ERROR" ], "description": "The acquirer response has an error. Retry at any time." }, { "enum": [ "SECURITY_CODE_MISMATCH" ], "description": "The security code is incorrect. Advise the customer to review the security code." }, { "enum": [ "TIMEOUT" ], "description": "The connection timed out. Retry at any time." }, { "enum": [ "TRANSACTION_NOT_FOUND" ], "description": "The referenced transaction was not found." }, { "enum": [ "UNDER_REVIEW" ], "description": "The transaction is under review." }, { "enum": [ "UNKNOWN_ERROR" ], "description": "The acquirer experienced an unknown error. Retry at any time." } ], "example": "ACCEPTED" }, "card-transaction-status": { "x-schema-group": "Shared", "type": "object", "title": "Transaction Status Cards", "description": "A JSON object that represents the card transaction status.\n", "properties": { "acquirer": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The acquirer that processed the transaction.\n", "example": "EBANX" }, "code": { "oneOf": [ { "$ref": "#/components/schemas/transaction-status-code" } ], "description": "The transaction status code.\n", "example": "OK" }, "description": { "type": "string", "description": "The description for the status code. Common values include: Accepted, Not accepted,\nInsufficient funds, Expired card, etc. In sandbox environments, may return\ntest-specific descriptions. See [Card Response Codes](https://docs.ebanx.com/docs/pay-in/dev-tools/response-codes)\nfor the full list.\n", "example": "Accepted" }, "description_code": { "oneOf": [ { "$ref": "#/components/schemas/card-description-code" } ], "nullable": true, "description": "Machine-readable decline or acceptance reason code.\n", "example": "ACCEPTED" }, "authcode": { "type": "string", "description": "The authorization code returned by the acquirer.\n", "example": "12345" }, "details": { "nullable": true, "description": "Additional details about the transaction status from the acquirer.\nMay be an object with structured data or a string with a description.\n" }, "iso_code": { "type": "string", "example": "00", "nullable": true, "description": "ISO 8583 response code from the acquirer.\n" }, "mac_code": { "type": "string", "example": "1A2B3C4D5E6F", "nullable": true, "description": "MAC (Message Authentication Code) from the acquirer response.\n" }, "brand_mandate": { "type": "object", "title": "Brand Mandate", "nullable": true, "description": "Present only when the transaction was blocked by Brand Mandate and all acquirer routes were exhausted.\nWhen present, `description` = \"Transaction blocked by Brand Mandate\" and `description_code` = \"BLOCKED_BY_BRAND_MANDATE\".\n", "properties": { "brand": { "type": "string", "description": "Card brand that triggered the mandate block.", "example": "mastercard" }, "blocking_category": { "type": "string", "description": "The mandate blocking category name.", "enum": [ "CANNOT_APPROVE_NOW", "DATA_ERROR", "GENERIC_ERROR", "WILL_NEVER_APPROVE" ], "example": "CANNOT_APPROVE_NOW" }, "blocking_category_code": { "type": "integer", "description": "Numeric code for the blocking category.", "enum": [ 1, 2, 3, 4 ], "example": 2 }, "blocking_window": { "type": "string", "description": "The time window in which the block applies.", "example": "24h" }, "attempt_count": { "type": "integer", "description": "Number of attempts registered in the current blocking window.", "example": 7 }, "limit": { "type": "object", "title": "Limit", "description": "Maximum attempt limits per time window.", "properties": { "daily": { "type": "integer", "nullable": true, "description": "Maximum attempts allowed in 24h window.", "example": 7 }, "monthly": { "type": "integer", "nullable": true, "description": "Maximum attempts allowed in 720h/monthly window.", "example": 35 } } }, "retry_after": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp indicating when the merchant can retry.", "example": "2026-05-05T14:30:00Z" } } } } }, "transaction-reference-2": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Payment Transaction Reference", "description": "A transaction reference returned in a payment response.\n", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The reference type. `arn` is an acquirer reference number and `tlid` is a\ntransaction link identifier.\n", "enum": [ "arn", "tlid" ], "example": "arn" }, "value": { "type": "string", "nullable": true, "description": "The reference value. This is `null` for an ARN that is pending or not\nsupported, and contains the reference value when it is available.\n", "example": "12345678901234567890123" }, "status": { "type": "string", "x-conditional": "Present for `arn` entries in Query responses", "description": "The availability status of an ARN. `available` indicates that the ARN\nvalue is available, `not_supported` indicates that the acquirer does not\nsupport the ARN, and `pending` indicates that the ARN is still being\nobtained.\n", "enum": [ "available", "not_supported", "pending" ], "example": "available" }, "installment": { "type": "integer", "minimum": 1, "x-conditional": "Present for `arn` entries in Query responses for payments with multiple installments", "description": "The installment number associated with this ARN.\n", "example": 1 } } }, "threeds-authentication-status": { "title": "3DS Authentication Status", "x-schema-group": "Response Codes", "type": "string", "description": "Status of the 3D Secure authentication flow.\n", "oneOf": [ { "enum": [ "PENDING_AUTHENTICATION" ], "description": "Authentication is in progress. The cardholder has not yet completed the challenge or the issuer has not responded." }, { "enum": [ "AUTHENTICATION_DONE" ], "description": "Authentication completed successfully. The cardholder was verified by the issuer." }, { "enum": [ "UNABLE_TO_AUTHENTICATE" ], "description": "Authentication could not be performed. The issuer or directory server was unreachable or returned an unsupported response." }, { "enum": [ "ERROR_CHECKING_AUTHENTICATION" ], "description": "An error occurred while verifying the authentication result after the challenge flow." }, { "enum": [ "TIMEOUT_AUTHENTICATION" ], "description": "The authentication request timed out before a response was received from the issuer." } ], "example": "AUTHENTICATION_DONE" }, "threedsecure-attempt": { "x-schema-group": "Shared", "type": "object", "title": "3DS Attempt", "description": "Details of a single 3DS authentication attempt.\n", "required": [ "ares", "rreq" ], "properties": { "attempt_number": { "type": "integer", "description": "The sequential number of this authentication attempt.\n", "example": 1 }, "attempt_status": { "description": "The status of this authentication attempt.\n", "allOf": [ { "$ref": "#/components/schemas/threeds-authentication-status" } ], "example": "AUTHENTICATION_DONE" }, "threeds_reference": { "type": "string", "description": "The unique reference identifier for this 3DS authentication attempt.\n", "example": "3DS2412632847456" }, "challenge": { "type": "boolean", "description": "Whether the cardholder went through a challenge flow (`true`) or a\nfrictionless flow (`false`) during this 3DS authentication attempt.\n", "example": false }, "eci": { "type": "string", "description": "Electronic Commerce Indicator returned by the card scheme.\n", "example": "02" }, "status_reason": { "type": "string", "example": "Cardholder authentication failed", "description": "The reason for the authentication status when not successful.\n" }, "ares": { "type": "string", "nullable": true, "description": "Authentication Response (ARes): the issuer's response to the\nauthentication request, indicating whether the payment was approved\nfrictionlessly or requires a challenge.\n", "example": "Y" }, "rreq": { "type": "string", "nullable": true, "description": "Results Request (RReq): the message sent by the Access Control Server\n(ACS) to the Directory Server (DS), detailing the results of the\nchallenge presented to the cardholder.\n", "example": "Y" }, "pares_status": { "type": "string", "description": "The Payer Authentication Response status from the issuer.\n", "example": "Y" }, "pares_status_description": { "type": "string", "description": "Human-readable description of the pares_status.\n", "example": "Customer was successfully authenticated." }, "threeds_cryptogram": { "type": "string", "description": "The Cardholder Authentication Verification Value (CAVV) generated during\nauthentication, proving the 3DS authentication took place.\n", "example": "AAABBWcSNIcAAAAAAAAAAAAAAAA=" }, "threeds_version": { "type": "string", "description": "The version of the EMVCo 3DS protocol used in the authentication.\n", "example": "2.2.0" } } }, "threeds-liability": { "title": "3DS Liability", "x-schema-group": "Response Codes", "type": "string", "description": "Indicates which party is liable for chargebacks on a 3DS-authenticated transaction.\n", "oneOf": [ { "enum": [ "ISSUER_BANK" ], "description": "Liability shift to the issuer bank. The merchant is protected from chargebacks resulting from fraud." }, { "enum": [ "MERCHANT" ], "description": "Liability remains with the merchant. The 3DS authentication did not result in a liability shift." }, { "enum": [ "NOT_IDENTIFIED" ], "description": "Liability could not be determined. The authentication result was inconclusive or the acquirer did not provide liability information." } ], "example": "ISSUER_BANK" }, "threedsecure-result": { "x-schema-group": "Shared", "type": "object", "title": "3DS Result", "description": "The final 3DS authentication result for the payment.\nExtends the attempt fields with a liability indicator.\n", "allOf": [ { "$ref": "#/components/schemas/threedsecure-attempt" }, { "type": "object", "title": "Threedsecure Result Extra Fields", "properties": { "liability": { "description": "Indicates which party is liable for chargebacks on this transaction.\n", "allOf": [ { "$ref": "#/components/schemas/threeds-liability" } ], "example": "ISSUER_BANK" } } } ] }, "threedsecure": { "x-schema-group": "Shared", "type": "object", "title": "3D Secure", "description": "3D Secure 2.0 authentication details for the payment.\nPresent when 3DS authentication was initiated for the transaction.\n", "properties": { "has_threeds": { "type": "boolean", "description": "Whether the payment went through 3D Secure authentication.\n", "example": true }, "status": { "description": "The overall 3DS authentication status.\n", "allOf": [ { "$ref": "#/components/schemas/threeds-authentication-status" } ], "example": "AUTHENTICATION_DONE" }, "threeds_redirect_url": { "type": "string", "description": "The URL to redirect the customer for 3DS authentication challenge.\nPresent when using EBANX Direct API Authentication mode.\n", "example": "https://ui-elements.ebanx.com/three-d-secure?auth_token=..." }, "threeds_attempts": { "type": "array", "description": "List of 3DS authentication attempts for the payment.\n", "items": { "$ref": "#/components/schemas/threedsecure-attempt" } }, "threeds_result": { "description": "The final 3DS authentication result for the payment.\nNull while authentication is still pending.\n", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/threedsecure-result" } ], "example": null } } }, "cof-info": { "x-schema-group": "Shared", "type": "object", "title": "Card on File Info Response", "description": "Card on File (COF) transaction details.\nPresent when the payment was processed with Card on File parameters.\n", "properties": { "cof_type": { "oneOf": [ { "$ref": "#/components/schemas/cof-type" } ], "description": "The type of Card on File transaction.\n", "example": "INITIAL" }, "initiator": { "oneOf": [ { "$ref": "#/components/schemas/cof-initiator" } ], "description": "Who initiated the transaction.\n", "example": "CIT" }, "mandate_id": { "type": "string", "nullable": true, "description": "Links the transaction with a previous agreement (mandate) that allows\nthe merchant to charge the customer repeatedly. Format varies by card brand.\nNull when COF has not been fully set up yet.\n", "example": "MCCABC1XY0101" }, "trans_type": { "oneOf": [ { "$ref": "#/components/schemas/cof-trans-type" } ], "description": "The type of COF transaction.\n", "example": "CUSTOMER_COF" } } }, "card-update": { "x-schema-group": "Shared", "type": "object", "title": "Card Update", "description": "Updated card information returned when the card updater service\ndetects that the card details have changed (e.g., new expiration date or replacement card).\n", "properties": { "new_card_bin": { "type": "string", "description": "The new BIN (first 6 digits) of the updated card.\n", "example": "411111" }, "new_card_last4": { "type": "string", "description": "The new last 4 digits of the updated card.\n", "example": "1111" }, "new_card_due_date": { "type": "string", "description": "The new expiration date of the updated card.\n", "example": "12/2028" } } }, "card-response": { "x-schema-group": "Shared", "title": "Card Payment Response", "description": "Response payment object for card payments (credit card and debit card).\nThis is a multi-country payment method — the same card integration works across\nall supported countries with minimal changes (country, currency, and document fields).\nThe values of `country` and `currency_ext` correspond to those sent in the request.\n", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Card Response Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "creditcard" }, "transaction_status": { "$ref": "#/components/schemas/card-transaction-status" }, "pre_approved": { "type": "boolean", "example": true }, "capture_available": { "type": "boolean", "example": false }, "transaction_references": { "type": "array", "description": "Transaction references associated with the payment. Present only for card\npayments that have at least one reference.\n", "items": { "$ref": "#/components/schemas/transaction-reference-2" } }, "token": { "type": "string", "description": "The EBANX token associated with the card used in this payment.\nPresent when tokenization was requested (via `create_token` or EBANX Token).\n", "example": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6" }, "token_available": { "type": "boolean", "description": "Whether a token was created or is available for this payment.\n", "example": true }, "masked_card_number": { "type": "string", "description": "The masked card number associated with the token.\n", "example": "411111xxxxxx1111" }, "threedsecure": { "$ref": "#/components/schemas/threedsecure" }, "cof_info": { "$ref": "#/components/schemas/cof-info" }, "card_update": { "$ref": "#/components/schemas/card-update" }, "redirect_url": { "type": "string", "nullable": true, "description": "URL to redirect the customer to complete authentication.\nPresent for card payments that require a 3DS / partner redirect.\n", "example": "https://sandbox.ebanxpay.com/threedsecure/redirect?hash=abc123" } } } ] }, "ar-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Argentina Response Base", "properties": { "country": { "type": "string", "example": "ar" }, "currency_ext": { "type": "string", "example": "USD" } } }, "banktransfer-3": { "x-schema-group": "Responses", "title": "Argentina Bank Transfer Payment Response", "description": "Response payment object for Argentina Bank Transfer payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ar-response-base" }, { "type": "object", "title": "Banktransfer Extra Fields", "properties": { "currency_ext": { "type": "string", "example": "ARS" }, "payment_type_code": { "type": "string", "example": "banktransfer" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "cupon-2": { "x-schema-group": "Responses", "title": "Argentina Cupon de Pagos Payment Response", "description": "Response payment object for Argentina Cupon de Pagos payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ar-response-base" }, { "type": "object", "title": "Cupon Extra Fields", "properties": { "currency_ext": { "type": "string", "example": "ARS" }, "payment_type_code": { "type": "string", "example": "cupon" }, "voucher_url": { "type": "string", "description": "The URL for the Cupon de Pagos payment voucher.", "example": "https://merchant.example.com/voucher" }, "pre_approved": { "description": "Flag that shows if a payment is pre-approved.", "type": "boolean", "example": false } } } ] }, "debin-2": { "x-schema-group": "Responses", "title": "Argentina DEBIN Payment Response", "description": "Response payment object for Argentina Debin payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ar-response-base" }, { "type": "object", "title": "DEBIN Extra Fields", "properties": { "currency_ext": { "type": "string", "example": "ARS" }, "payment_type_code": { "type": "string", "example": "debin" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "mercadopago-response-base": { "x-hidden": true, "x-schema-group": "Responses", "title": "Mercado Pago Wallet Payment Response", "description": "Response payment object for Mercado Pago Wallet payments.\nThis is a multi-country payment method — the same integration works across\nall supported countries (AR, BR, CL, MX, UY) with minimal changes\n(country, currency, and document fields).\nThe values of `country` and `currency_ext` correspond to those sent in the request.\n", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Mercado Pago Response Base Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "mercadopago" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to the Mercado Pago checkout page\nto complete the payment.\n", "example": "https://acquirer.redirect.example.com" }, "ewallet_payment_method": { "type": "string", "description": "The funding source selected by the customer within the Mercado Pago wallet.\n", "example": "ACCOUNT_BALANCE" }, "ewallet_installments": { "type": "string", "description": "The number of installments chosen by the customer within the Mercado Pago wallet.\n", "example": "3" } } } ] }, "enrollment-status-response": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Status Response", "description": "Enrollment status summary returned with recurring payment charges and enrollment operations.\nShared between ws/direct (recurring charge) and ws/userenrollment. Composed into the full\nenrollment response object.\n", "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant's unique enrollment code.", "example": "my-enrollment-code-123" }, "status": { "type": "string", "description": "Current enrollment (agreement contract) status.", "example": "ACCEPTED" }, "status_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "Date/time of the last enrollment status change. Present when a reason code is available.", "example": "2024-12-15 10:30:00" }, "reason_code": { "type": "string", "nullable": true, "description": "Reason code for the current enrollment status, when available from the provider.", "example": "DS04" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description of the reason for the status change.", "example": "Enrollment cancelled by merchant request" }, "confirm_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "Date/time the enrollment was accepted/confirmed. Returned in the query response for\nNequi recurrent enrollments.\n", "example": "2024-12-15 10:30:00" }, "redirect_url": { "type": "string", "nullable": true, "deprecated": true, "description": "Deprecated. Sandbox-only redirect URL echoed inside the enrollment object for Nequi recurrent\nlegacy enroll-and-charge. Use the top-level `redirect_url` instead.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" }, "payment_execution_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "Scheduled execution date/time of the charge linked to this enrollment. Returned in the query\nresponse for enrollment-based payments using the notify-then-charge flow.\n", "example": "2024-12-15 10:30:00" }, "notification_hash": { "type": "string", "nullable": true, "description": "Hash of the pre-charge notification associated with this enrollment payment, when available.\n", "example": "abc123def456" } } }, "mpconnect-response-base": { "x-hidden": true, "x-schema-group": "Responses", "title": "Mercado Pago Connect Payment Response", "description": "Response payment object for Mercado Pago Connect recurring payments.\nThis is a multi-country payment method — the same integration works across\nall supported countries (AR, BR, CL, MX, UY) with minimal changes\n(country, currency, and document fields).\nThe values of `country` and `currency_ext` correspond to those sent in the request.\n", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Mercado Pago Connect Response Base Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "mpconnect" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" } } } ] }, "pago-facil-2": { "x-schema-group": "Responses", "title": "Argentina Pago Facil Payment Response", "description": "Response payment object for Argentina PagoFacil payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ar-response-base" }, { "type": "object", "title": "Pago Facil Extra Fields", "properties": { "currency_ext": { "type": "string", "example": "ARS" }, "payment_type_code": { "type": "string", "example": "pagofacil" }, "voucher_url": { "type": "string", "description": "The URL for the PagoFacil payment voucher.", "example": "https://merchant.example.com/voucher" }, "pre_approved": { "description": "Flag that shows if a payment is pre-approved.", "type": "boolean", "example": false } } } ] }, "rapi-pago-2": { "x-schema-group": "Responses", "title": "Argentina Rapi Pago Payment Response", "description": "Response payment object for Argentina RapiPago payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ar-response-base" }, { "type": "object", "title": "RapiPago Extra Fields", "properties": { "currency_ext": { "type": "string", "example": "ARS" }, "payment_type_code": { "type": "string", "example": "rapipago" }, "voucher_url": { "type": "string", "description": "The URL for the RapiPago payment voucher.", "example": "https://merchant.example.com/voucher" }, "pre_approved": { "description": "Flag that shows if a payment is pre-approved.", "type": "boolean", "example": false } } } ] }, "cryptocurrency": { "x-schema-group": "Shared", "type": "object", "title": "Cryptocurrency", "description": "Stablecoin payment details including the crypto amount, exchange rate,\nand supported blockchain protocols with QR codes and wallet addresses.\n", "properties": { "amount": { "type": "string", "description": "The payment amount in the selected stablecoin.\n", "example": "99.85" }, "crypto_rate": { "type": "string", "description": "The exchange rate between the local currency and the stablecoin.\n", "example": "5.4167000000" }, "wallet_connect_url": { "type": "string", "format": "uri", "description": "EBANX URL that takes the customer to the wallet-connection option to complete the payment.\nOnly present when the wallet-connection option is available for the payment.\n", "example": "https://sandbox.ebanx.com/ws/redirect?hash=6abe8fa5a9d0d0e75b30d794589258f89bc462ba06b73a5a" }, "protocols": { "type": "array", "description": "List of supported blockchain protocols with QR codes and wallet addresses.\nDisplay the protocol matching the network selected by the customer at checkout.\n", "items": { "type": "object", "title": "Blockchain Protocol", "properties": { "qr_code_value": { "type": "string", "description": "Base64-encoded QR code image for the payment address.\n", "example": "data:image/png;base64,iVB...YII=" }, "address": { "type": "string", "description": "The destination wallet address for the payment.\n", "example": "0x750be138124c34a1507671c5a717e74605d87bef" }, "protocol": { "type": "string", "description": "The blockchain protocol/network.\n", "example": "ERC20" } } } } } }, "stablecoin-response-base": { "x-hidden": true, "x-schema-group": "Responses", "title": "Stablecoin Payment Response", "description": "Response payment object for stablecoin payments.\nThis is a multi-country payment method — the same integration works across\nall supported countries with minimal changes (country, currency, and document fields).\nThe values of `country` and `currency_ext` correspond to those sent in the request.\n", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Stablecoin Response Base Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "usdt" }, "currency_ext": { "description": "The source currency code (ISO 4217 three-letter code or stablecoin ticker). Mirrors the value sent in the request.\n", "enum": [ "ARS", "BRL", "CLP", "MXN", "PEN", "USD", "USDC", "USDT", "UYU" ], "type": "string", "maxLength": 4, "example": "USDT" }, "cryptocurrency": { "$ref": "#/components/schemas/cryptocurrency" } } } ] }, "payment-response": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇦🇷 Argentina", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/banktransfer-3" }, { "$ref": "#/components/schemas/cupon-2" }, { "$ref": "#/components/schemas/debin-2" }, { "$ref": "#/components/schemas/mercadopago-response-base" }, { "$ref": "#/components/schemas/mpconnect-response-base" }, { "$ref": "#/components/schemas/pago-facil-2" }, { "$ref": "#/components/schemas/rapi-pago-2" }, { "$ref": "#/components/schemas/stablecoin-response-base" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "cabal": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "naranja": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "banktransfer": "#/components/schemas/banktransfer-3", "cupon": "#/components/schemas/cupon-2", "debin": "#/components/schemas/debin-2", "mercadopago": "#/components/schemas/mercadopago-response-base", "mpconnect": "#/components/schemas/mpconnect-response-base", "mpcredito": "#/components/schemas/mercadopago-response-base", "pagofacil": "#/components/schemas/pago-facil-2", "rapipago": "#/components/schemas/rapi-pago-2", "usdc": "#/components/schemas/stablecoin-response-base", "usdt": "#/components/schemas/stablecoin-response-base" } } }, "pagos-net-2": { "x-schema-group": "Responses", "title": "Bolivia PagosNet Payment Response", "description": "Response payment object for Bolivia PagosNet payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "PagosNet Extra Fields", "properties": { "country": { "type": "string", "example": "bo" }, "currency_ext": { "type": "string", "example": "BOB" }, "payment_type_code": { "type": "string", "example": "pagosnet" }, "token": { "type": "string", "description": "Payment token identifier for PagosNet voucher reference.\n", "example": "PAGOSNET-TOKEN-123456" }, "voucher_url": { "type": "string", "description": "URL to the payment voucher.\n", "example": "https://customer.ebanx.com/voucher" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "payment-response-2": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇧🇴 Bolivia", "oneOf": [ { "$ref": "#/components/schemas/pagos-net-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "pagosnet": "#/components/schemas/pagos-net-2" } } }, "br-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Brazil Response Base", "properties": { "country": { "type": "string", "example": "br" }, "currency_ext": { "type": "string", "example": "BRL" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "bank-transfer-4": { "x-schema-group": "Responses", "title": "Brazil Bank Transfer Payment Response", "description": "Response payment object for Brazil Bank Transfer payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Bank Transfer Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "banktransfer" } } } ] }, "boleto-2": { "x-schema-group": "Responses", "title": "Brazil Boleto Payment Response", "description": "Response payment object for Brazil Boleto payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Boleto Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "boleto" }, "boleto_url": { "type": "string", "nullable": true, "description": "URL to display the boleto to the customer.\n", "example": "https://sandbox.ebanxpay.com/print/?hash=abc123" }, "boleto_barcode": { "type": "string", "nullable": true, "description": "Formatted boleto barcode (with spaces/dots for display).\n", "example": "34191.79001 01043.510047 91020.150008 1 84340000010000" }, "boleto_barcode_raw": { "type": "string", "nullable": true, "description": "Raw numeric boleto barcode (digits only, for copy/paste).\n", "example": "34191843400000100001790010104351004791020150" } } } ] }, "boleto-pix-2": { "x-schema-group": "Responses", "title": "Brazil BoletoPix Payment Response", "description": "Response payment object for Brazil BoletoPix hybrid payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Boleto Pix Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "boletopix" }, "boleto_url": { "type": "string", "nullable": true, "description": "URL to display the boleto to the customer.", "example": "https://sandbox.ebanxpay.com/print/?hash=abc123" }, "boleto_barcode": { "type": "string", "nullable": true, "description": "Formatted boleto barcode (with spaces/dots for display).", "example": "34191.79001 01043.510047 91020.150008 1 84340000010000" }, "boleto_barcode_raw": { "type": "string", "nullable": true, "description": "Raw numeric boleto barcode (digits only, for copy/paste).", "example": "34191843400000100001790010104351004791020150" }, "pix": { "type": "object", "title": "Pix", "description": "Pix-specific response data for the BoletoPix hybrid payment.", "properties": { "qr_code_value": { "type": "string", "description": "The Pix QR code value.", "example": "00020126580014br.gov.bcb.pix" } } } } } ] }, "directdebit-4": { "x-schema-group": "Responses", "title": "Brazil Direct Debit Payment Response", "description": "Response payment object for Brazil Direct Debit payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Directdebit Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "directdebit" } } } ] }, "ebx-banktransfer-sub-2": { "x-schema-group": "Responses", "title": "Brazil Bank Transfer Subscription Payment Response", "description": "Response payment object for Brazil bank transfer subscription payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Ebx Banktransfer Sub Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "ebx-banktransfer-sub" } } } ] }, "nu-pay-2": { "x-schema-group": "Responses", "title": "Brazil NuPay Payment Response", "description": "Response payment object for Brazil NuPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "NuPay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "nupay" } } } ] }, "nu-pay-recurring-2": { "x-schema-group": "Responses", "title": "Brazil NuPay Recurring Payment Response", "description": "Response payment object for Brazil NuPayRecurring payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "NuPay Recurring Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "nupay-recurrent" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" } } } ] }, "paypal-2": { "x-schema-group": "Responses", "title": "Brazil PayPal Payment Response", "description": "Response payment object for Brazil PayPal payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "PayPal Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "paypal" } } } ] }, "pic-pay-2": { "x-schema-group": "Responses", "title": "Brazil PicPay Payment Response", "description": "Response payment object for Brazil PicPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "PicPay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "picpay" } } } ] }, "payer-details": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Pix Payer Details", "description": "Details about the payer of a Pix payment. Present for confirmed payments when payer data is available.\n", "properties": { "end_to_end_id": { "type": "string", "description": "The Pix end-to-end identifier.", "example": "E00000000202406151000abcdef123456" }, "document": { "type": "string", "description": "The payer document number.", "example": "853.513.468-93" }, "name": { "type": "string", "description": "The payer name.", "example": "João Santos" }, "bank_name": { "type": "string", "description": "The payer bank name.", "example": "Banco do Brasil" }, "bank_ispb": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "The payer bank ISPB code.", "example": 0 }, "agency_number": { "type": "string", "description": "The payer bank agency number.", "example": "1234" }, "account_number": { "type": "string", "description": "The payer bank account number.", "example": "56789-0" }, "account_type": { "type": "string", "description": "The payer bank account type.", "example": "CHECKING" } } }, "customer-action-details": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Pix Customer Action Details", "description": "Details about the customer's interaction with the Pix QR code.\nPresent for confirmed or cancelled Pix payments when scan data is available.\n", "properties": { "qr_code_scan_count": { "type": "integer", "description": "Number of times the customer scanned the Pix QR code.", "example": 2 }, "last_qr_code_scan": { "type": "string", "nullable": true, "description": "Date and time of the last QR code scan (UTC). Null when not scanned.", "example": "2027-06-12 12:30:40" }, "customer_bank_name": { "type": "string", "nullable": true, "description": "Name of the payer's bank. Present only for confirmed payments when available.\n", "example": "Banco do Brasil" } } }, "pix-2": { "x-schema-group": "Responses", "title": "Brazil Pix Payment Response", "description": "Response payment object for Brazil Pix payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Pix Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "pix" }, "pix": { "type": "object", "title": "Pix", "description": "Pix-specific response data.", "properties": { "qr_code_value": { "type": "string", "description": "The Pix QR code value.", "example": "00020126580014br.gov.bcb.pix" }, "information": { "type": "object", "title": "Information", "nullable": true, "description": "Additional Pix payment information.", "additionalProperties": true }, "payer_details": { "allOf": [ { "$ref": "#/components/schemas/payer-details" }, { "type": "object", "title": "Pix Payer Fingerprint", "properties": { "fingerprint": { "type": "string", "description": "Deterministic, non-reversible identifier of the payer document, allowing the merchant to\nrecognize the same payer across payments without receiving the document itself.\n", "example": "MGPRU/og0HpKJnG77DjfJ0RN/4hlOaH01dIcr9FdIrs=" } } } ] }, "customer_action_details": { "$ref": "#/components/schemas/customer-action-details" } } } } } ] }, "subscription-response": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Subscription Response", "description": "Subscription details returned in enrollment and recurring payment responses. Shared between\nws/direct (recurring charge) and ws/userenrollment (standalone enrollment). The applicable fields\nvary by payment method; the amount fields are mutually exclusive: `fixed_amount` for fixed-value\nsubscriptions; `max_amount_floor` (Pix Automático) or `min_amount` + `max_amount` for\nvariable-value subscriptions.\n", "properties": { "subscription_name": { "type": "string", "nullable": true, "description": "Name of the subscription.", "example": "Monthly subscription" }, "start_date": { "type": "string", "format": "date", "description": "Start date of the subscription.", "example": "2024-12-15" }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "Expiration date of the subscription.", "example": "2025-12-30" }, "frequency": { "type": "string", "description": "Frequency of the subscription.", "enum": [ "onetime", "daily", "weekly", "fortnightly", "monthly", "bimonthly", "quarterly", "halfyearly", "yearly", "biennially", "ondemand" ], "example": "monthly" }, "retry": { "type": "string", "nullable": true, "description": "Retry policy for failed payments.", "enum": [ "allow_3R_7D", "not_allowed" ], "example": "allow_3R_7D" }, "fixed_amount": { "type": "string", "nullable": true, "description": "Fixed amount charged on each cycle (fixed-value subscriptions).", "example": "500.00" }, "min_amount": { "type": "string", "nullable": true, "description": "Minimum amount allowed per charge (variable-value subscriptions).", "example": "100.00" }, "max_amount": { "type": "string", "nullable": true, "description": "Maximum amount allowed per charge (variable-value subscriptions).", "example": "500.00" }, "max_amount_floor": { "type": "string", "nullable": true, "description": "Maximum amount floor for variable Pix Automático subscriptions.", "example": "5.00" }, "qr_code_value": { "type": "string", "nullable": true, "description": "QR code value for Pix Automático enrollment.", "example": "00020101021226780014br.gov.bcb.pix2556fake-pix.com.br/qr/v2/..." } } }, "pix-automatico-2": { "x-schema-group": "Responses", "title": "Brazil Pix Automatico Payment Response", "description": "Response payment object for Brazil PixAutomatico payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Pix Automatico Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "pix-automatico" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" }, "subscription": { "$ref": "#/components/schemas/subscription-response" }, "pix_automatico": { "type": "object", "title": "Pix Automatico", "nullable": true, "description": "Pix Automático recurring payment data. Present only for Pix Automático payments.\n", "properties": { "qr_code_value": { "type": "string", "description": "The Pix Automático mandate QR code value.", "example": "00020126580014br.gov.bcb.pix" } } }, "pix": { "type": "object", "title": "Pix", "description": "Pix-specific response data.", "properties": { "qr_code_value": { "type": "string", "description": "The Pix QR code value.", "example": "00020126580014br.gov.bcb.pix" }, "payer_details": { "$ref": "#/components/schemas/payer-details" }, "customer_action_details": { "$ref": "#/components/schemas/customer-action-details" } } } } } ] }, "pix-pisp-2": { "x-schema-group": "Responses", "title": "Brazil Pix PISP Payment Response", "description": "Response payment object for Brazil Pix PISP payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/br-response-base" }, { "type": "object", "title": "Pix Pisp Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "pix-pisp" }, "pix": { "type": "object", "title": "Pix", "description": "Pix-specific response data for the Pix PISP payment.", "properties": { "qr_code_value": { "type": "string", "description": "The Pix QR code value.", "example": "00020126580014br.gov.bcb.pix" } } } } } ] }, "payment-response-3": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇧🇷 Brazil", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/bank-transfer-4" }, { "$ref": "#/components/schemas/boleto-pix-2" }, { "$ref": "#/components/schemas/boleto-2" }, { "$ref": "#/components/schemas/directdebit-4" }, { "$ref": "#/components/schemas/ebx-banktransfer-sub-2" }, { "$ref": "#/components/schemas/mercadopago-response-base" }, { "$ref": "#/components/schemas/mpconnect-response-base" }, { "$ref": "#/components/schemas/nu-pay-recurring-2" }, { "$ref": "#/components/schemas/nu-pay-2" }, { "$ref": "#/components/schemas/paypal-2" }, { "$ref": "#/components/schemas/pic-pay-2" }, { "$ref": "#/components/schemas/pix-automatico-2" }, { "$ref": "#/components/schemas/pix-pisp-2" }, { "$ref": "#/components/schemas/pix-2" }, { "$ref": "#/components/schemas/stablecoin-response-base" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "elo": "#/components/schemas/card-response", "hipercard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "banktransfer": "#/components/schemas/bank-transfer-4", "boleto": "#/components/schemas/boleto-2", "boletopix": "#/components/schemas/boleto-pix-2", "directdebit": "#/components/schemas/directdebit-4", "ebx-banktransfer-sub": "#/components/schemas/ebx-banktransfer-sub-2", "mercadopago": "#/components/schemas/mercadopago-response-base", "mpconnect": "#/components/schemas/mpconnect-response-base", "mpcredito": "#/components/schemas/mercadopago-response-base", "nupay": "#/components/schemas/nu-pay-2", "nupay-recurrent": "#/components/schemas/nu-pay-recurring-2", "paypal": "#/components/schemas/paypal-2", "picpay": "#/components/schemas/pic-pay-2", "pix": "#/components/schemas/pix-2", "pix-automatico": "#/components/schemas/pix-automatico-2", "pix-pisp": "#/components/schemas/pix-pisp-2", "usdc": "#/components/schemas/stablecoin-response-base", "usdt": "#/components/schemas/stablecoin-response-base" } } }, "cl-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Chile Response Base", "properties": { "country": { "type": "string", "example": "cl" }, "currency_ext": { "type": "string", "example": "CLP" } } }, "bank-transfer-5": { "x-schema-group": "Responses", "title": "Chile Bank Transfer Payment Response", "description": "Response payment object for Chile BankTransfer payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/cl-response-base" }, { "type": "object", "title": "Bank Transfer Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "banktransfer" }, "voucher_url": { "type": "string", "description": "URL to the bank transfer payment voucher.\n", "example": "https://customer.ebanx.com/voucher" }, "customer": { "type": "object", "title": "Customer", "description": "Customer information returned in the response.", "properties": { "document": { "type": "string", "description": "Customer's RUT (taxpayer identification number).", "example": "9882884-2" }, "email": { "type": "string", "description": "Customer's email address.", "example": "jose@example.com" }, "name": { "type": "string", "example": "John Doe", "description": "Customer's full name." }, "birth_date": { "type": "string", "format": "date", "description": "Customer's date of birth.", "example": "1990-03-15" } } }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "mach-pay-2": { "x-schema-group": "Responses", "title": "Chile MACH Pay Payment Response", "description": "Response payment object for Chile MachPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/cl-response-base" }, { "type": "object", "title": "MACH Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "machpay" }, "ewallet": { "type": "object", "title": "Ewallet", "description": "E-wallet specific response data for MACH Pay.", "properties": { "qr_code_value": { "type": "string", "description": "QR code value for MACH Pay payment.\n", "example": "https://machpay.cl/pay/qr/..." } } }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "multicaja-2": { "x-schema-group": "Responses", "title": "Chile Multicaja Payment Response", "description": "Response payment object for Chile Multicaja payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/cl-response-base" }, { "type": "object", "title": "Multicaja Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "multicaja" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "sencillito-2": { "x-schema-group": "Responses", "title": "Chile Sencillito Payment Response", "description": "Response payment object for Chile Sencillito payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/cl-response-base" }, { "type": "object", "title": "Sencillito Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "sencillito" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "servipag-2": { "x-schema-group": "Responses", "title": "Chile Servipag Payment Response", "description": "Response payment object for Chile Servipag payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/cl-response-base" }, { "type": "object", "title": "Servipag Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "servipag" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "web-pay-2": { "x-schema-group": "Responses", "title": "Chile WebPay Payment Response", "description": "Response payment object for Chile WebPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/cl-response-base" }, { "type": "object", "title": "Webpay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "webpay" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "payment-response-4": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇨🇱 Chile", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/bank-transfer-5" }, { "$ref": "#/components/schemas/mach-pay-2" }, { "$ref": "#/components/schemas/mercadopago-response-base" }, { "$ref": "#/components/schemas/mpconnect-response-base" }, { "$ref": "#/components/schemas/multicaja-2" }, { "$ref": "#/components/schemas/sencillito-2" }, { "$ref": "#/components/schemas/servipag-2" }, { "$ref": "#/components/schemas/stablecoin-response-base" }, { "$ref": "#/components/schemas/web-pay-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "banktransfer": "#/components/schemas/bank-transfer-5", "machpay": "#/components/schemas/mach-pay-2", "mercadopago": "#/components/schemas/mercadopago-response-base", "mpconnect": "#/components/schemas/mpconnect-response-base", "mpcredito": "#/components/schemas/mercadopago-response-base", "multicaja": "#/components/schemas/multicaja-2", "sencillito": "#/components/schemas/sencillito-2", "servipag": "#/components/schemas/servipag-2", "usdc": "#/components/schemas/stablecoin-response-base", "usdt": "#/components/schemas/stablecoin-response-base", "webpay": "#/components/schemas/web-pay-2", "webpay-rest": "#/components/schemas/web-pay-2", "webpayplus": "#/components/schemas/web-pay-2" } } }, "co-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Colombia Response Base", "properties": { "country": { "type": "string", "example": "co" }, "currency_ext": { "type": "string", "example": "COP" } } }, "pse-avanza-2": { "x-schema-group": "Responses", "title": "Colombia PSE Avanza Payment Response", "description": "Response payment object for Colombia PSEAvanza payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "PSE Avanza Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "achpse" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "baloto-2": { "x-schema-group": "Responses", "title": "Colombia Baloto Payment Response", "description": "Response payment object for Colombia Baloto payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Baloto Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "baloto" }, "baloto_url": { "type": "string", "description": "URL to the Baloto payment voucher.\n", "example": "https://sandbox.ebanxpay.com/print/baloto/?hash=6753669df5c6e02853a53f75d84e8f30572b205d5233a2ab" }, "voucher_id": { "type": "string", "description": "The voucher identifier for the Baloto payment.\n", "example": "81809966" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "bancolombia-2": { "x-schema-group": "Responses", "title": "Colombia Boton Bancolombia Payment Response", "description": "Response payment object for Colombia Bancolombia payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Bancolombia Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "bancolombia-button" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "breb-2": { "x-schema-group": "Responses", "title": "Colombia Bre-B Payment Response", "description": "Response payment object for Colombia Bre-B payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Bre-B Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "breb" }, "ewallet": { "type": "object", "title": "Ewallet", "description": "Bre-B-specific response data.", "properties": { "qr_code_value": { "type": "string", "description": "Base64-encoded QR code for the Bre-B payment.\n", "example": "data:image/png;base64,iVB...YII=" } } } } } ] }, "efecty-2": { "x-schema-group": "Responses", "title": "Colombia Efecty Payment Response", "description": "Response payment object for Colombia Efecty payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Efecty Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "efecty" }, "voucher_url": { "type": "string", "description": "URL to the Efecty payment voucher.\n", "example": "https://customer.ebanx.com/voucher" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "movii-2": { "x-schema-group": "Responses", "title": "Colombia Movii Payment Response", "description": "Response payment object for Colombia Movii wallet payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Movii Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "movii" }, "ewallet": { "type": "object", "title": "Ewallet", "description": "E-wallet specific response data for Movii.", "properties": { "qr_code_value": { "type": "string", "description": "QR code value for the Movii payment.", "example": "https://sandbox.ebanxpay.com/movii/qr" } } }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "nequi-2": { "x-schema-group": "Responses", "title": "Colombia Nequi Payment Response", "description": "Response payment object for Colombia Nequi payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Nequi Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "nequi" }, "ewallet": { "type": "object", "title": "Ewallet", "description": "E-wallet specific response data for Nequi.", "properties": { "qr_code_value": { "type": "string", "description": "QR code value for Nequi push payment.\n", "example": "https://nequi.com/pay/qr/..." }, "mobile_number": { "type": "string", "description": "The customer mobile number associated with the Nequi payment. Present on confirmed payments.\n", "example": "3001234567" }, "confirmation_method": { "type": "string", "description": "The Nequi confirmation method used by the customer.\n", "enum": [ "push_notification", "qr_code" ], "example": "push_notification" } } }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "nequi-recurring-2": { "x-schema-group": "Responses", "title": "Colombia Nequi Recurring Payment Response", "description": "Response payment object for Colombia NequiRecurring payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Nequi Recurring Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "nequi-recurrent" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "transfiya-2": { "x-schema-group": "Responses", "title": "Colombia Transfiya Payment Response", "description": "Response payment object for Colombia Transfiya payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/co-response-base" }, { "type": "object", "title": "Transfiya Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "transfiya" } } } ] }, "payment-response-5": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇨🇴 Colombia", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/baloto-2" }, { "$ref": "#/components/schemas/bancolombia-2" }, { "$ref": "#/components/schemas/breb-2" }, { "$ref": "#/components/schemas/efecty-2" }, { "$ref": "#/components/schemas/movii-2" }, { "$ref": "#/components/schemas/nequi-recurring-2" }, { "$ref": "#/components/schemas/nequi-2" }, { "$ref": "#/components/schemas/pse-avanza-2" }, { "$ref": "#/components/schemas/transfiya-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "codensa": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "elo": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "achpse": "#/components/schemas/pse-avanza-2", "baloto": "#/components/schemas/baloto-2", "bancolombia-button": "#/components/schemas/bancolombia-2", "breb": "#/components/schemas/breb-2", "efecty": "#/components/schemas/efecty-2", "eft": "#/components/schemas/pse-avanza-2", "movii": "#/components/schemas/movii-2", "nequi": "#/components/schemas/nequi-2", "nequi-recurrent": "#/components/schemas/nequi-recurring-2", "transfiya": "#/components/schemas/transfiya-2" } } }, "payment-response-6": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇨🇷 Costa Rica", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-7": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇩🇴 Dominican Republic", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "safety-pay-3": { "x-schema-group": "Responses", "title": "Ecuador SafetyPay Payment Response", "description": "Response payment object for Ecuador SafetyPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Safety Pay Extra Fields", "properties": { "country": { "type": "string", "example": "ec" }, "currency_ext": { "type": "string", "example": "USD" }, "payment_type_code": { "type": "string", "example": "safetypay" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "payment-response-8": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇪🇨 Ecuador", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/safety-pay-3" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "safetypay-cash": "#/components/schemas/safety-pay-3", "safetypay-online": "#/components/schemas/safety-pay-3" } } }, "eg-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Egypt Response Base", "properties": { "country": { "type": "string", "example": "eg" }, "currency_ext": { "type": "string", "example": "EGP" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "fawry-2": { "x-schema-group": "Responses", "title": "Egypt Fawry Payment Response", "description": "Response payment object for Egypt Fawry payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/eg-response-base" }, { "type": "object", "title": "Fawry Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "fawry" }, "fawry": { "type": "object", "title": "Fawry", "description": "Fawry-specific response data.", "properties": { "reference_number": { "type": "string", "description": "Fawry reference number for payment at Fawry locations.\n", "example": "1234567890" } } } } } ] }, "fawry-external-2": { "x-schema-group": "Responses", "title": "Egypt Fawry External Payment Response", "description": "Response payment object for Egypt Fawry External payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/eg-response-base" }, { "type": "object", "title": "Fawry External Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "fawry-external" }, "fawry": { "type": "object", "title": "Fawry", "description": "Fawry-specific response data.", "properties": { "reference_number": { "type": "string", "description": "Fawry reference number for payment at Fawry locations.\n", "example": "1234567890" } } } } } ] }, "mobile-wallets-2": { "x-schema-group": "Responses", "title": "Egypt Mobile Wallets Payment Response", "description": "Response payment object for Egypt MobileWallets payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/eg-response-base" }, { "type": "object", "title": "Mobile Wallets Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "meeza" } } } ] }, "payment-response-9": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇪🇬 Egypt", "oneOf": [ { "$ref": "#/components/schemas/fawry-external-2" }, { "$ref": "#/components/schemas/fawry-2" }, { "$ref": "#/components/schemas/mobile-wallets-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "fawry": "#/components/schemas/fawry-2", "fawry-external": "#/components/schemas/fawry-external-2", "meeza": "#/components/schemas/mobile-wallets-2" } } }, "mobile-money-2": { "x-schema-group": "Responses", "title": "Ghana Mobile Money Payment Response", "description": "Response payment object for Ghana MobileMoney payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Mobile Money Extra Fields", "properties": { "country": { "type": "string", "example": "gh" }, "currency_ext": { "type": "string", "example": "GHS" }, "payment_type_code": { "type": "string", "example": "mobile-money" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "payment-response-10": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇬🇭 Ghana", "oneOf": [ { "$ref": "#/components/schemas/mobile-money-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "airtel": "#/components/schemas/mobile-money-2", "mpesa": "#/components/schemas/mobile-money-2", "mtn": "#/components/schemas/mobile-money-2", "vodacom": "#/components/schemas/mobile-money-2" } } }, "payment-response-11": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇬🇹 Guatemala", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "id-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Indonesia Response Base", "properties": { "country": { "type": "string", "example": "id" }, "currency_ext": { "type": "string", "example": "IDR" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "dana-2": { "x-schema-group": "Responses", "title": "Indonesia DANA Payment Response", "description": "Response payment object for Indonesia DANA payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/id-response-base" }, { "type": "object", "title": "DANA Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "dana" } } } ] }, "ovo-recurring-2": { "x-schema-group": "Responses", "title": "Indonesia OVO Recurring Payment Response", "description": "Response payment object for Indonesia OVO Recurring payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/id-response-base" }, { "type": "object", "title": "OVO Recurring Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "ovo-recurring" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" }, "currency_ext_base": { "type": "string", "description": "Base external currency code.\n", "example": "IDR" } } } ] }, "virtual-account-2": { "x-schema-group": "Responses", "title": "Indonesia Virtual Account Payment Response", "description": "Response payment object for Indonesia Virtual Account payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/id-response-base" }, { "type": "object", "title": "Virtual Account Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "virtual-account" } } } ] }, "payment-response-12": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇮🇩 Indonesia", "oneOf": [ { "$ref": "#/components/schemas/dana-2" }, { "$ref": "#/components/schemas/ovo-recurring-2" }, { "$ref": "#/components/schemas/virtual-account-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "dana": "#/components/schemas/dana-2", "ovo-recurring": "#/components/schemas/ovo-recurring-2", "virtual-account": "#/components/schemas/virtual-account-2" } } }, "card-response-2": { "x-schema-group": "Responses", "title": "India Card Payment Response", "description": "Response payment object for India card payments. India card recurring is enrollment-based\n(it creates an agreement contract), so the response includes the `enrollment` object.\nThe `enrollment` object is present only for recurring card charges linked to an enrollment.\n", "allOf": [ { "$ref": "#/components/schemas/card-response" }, { "type": "object", "title": "Card Response Extra Fields", "properties": { "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" } } } ] }, "in-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "India Response Base", "properties": { "country": { "type": "string", "example": "in" }, "currency_ext": { "type": "string", "example": "INR" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "lrs-travel-2": { "x-schema-group": "Responses", "title": "India LRS Travel Payment Response", "description": "Response payment object for India LRS Travel payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/in-response-base" }, { "type": "object", "title": "LRS Travel Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "lrs-travel" }, "metadata": { "type": "object", "title": "LRS Travel Metadata", "x-conditional": "Returned once the payment is confirmed (`CO`)", "description": "How the payer actually paid, as reported by the provider once the payment is confirmed.\nOnly the fields known for the instrument used are returned.\n", "x-default-expanded": true, "properties": { "payment_method": { "type": "string", "description": "The instrument family the payer used, `upi` or `card`.\n", "example": "card" }, "payment_sub_type": { "type": "string", "description": "For UPI, the channel used (`collect`, `link` for intent payments, or `qrcode`).\nFor cards, the card type (`credit_card`, `debit_card` or `prepaid_card`).\n", "example": "credit_card" }, "instrument_type": { "type": "string", "description": "For UPI, the instrument funding the payment (for example, `UPI_Credit_Card`).\nFor cards, the card network (`visa`, `mastercard`, `rupay`, `amex` or `diners`).\n", "example": "visa" }, "order_amount": { "type": "string", "description": "The total amount charged to the payer, that is the requested amount plus the Tax\nCollected at Source (TCS) added on top of it.\n", "example": "75000.00" }, "tcs_amount": { "type": "string", "description": "The Tax Collected at Source (TCS) charged on top of the requested amount.\n", "example": "3750.00" }, "bank_reference_id": { "type": "string", "description": "The bank reference number (RRN) the provider reported for the payment.\n", "example": "202501151035" } } } } } ] }, "upi-3": { "x-schema-group": "Responses", "title": "India UPI Payment Response", "description": "Response payment object for India UPI payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/in-response-base" }, { "type": "object", "title": "UPI Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "upi" }, "upi": { "type": "object", "title": "Upi", "description": "UPI-specific response data.", "properties": { "qr_code_value": { "type": "string", "description": "QR code value for UPI Desktop (upi-qrcode) payments.\n", "example": "upi://pay?pa=..." }, "app_links": { "type": "array", "example": [ "gpay://upi/pay?pa=merchant@upi" ], "description": "Deep links for UPI Mobile (upi-intent) payments.\nEach item is a URI string (e.g. gpay://upi/pay?..., ppe://pay?...).\n", "items": { "type": "string" } }, "expiration_date": { "allOf": [ { "$ref": "#/components/schemas/not-nullable-datetime" } ], "description": "UPI payment expiration date/time.\n", "example": "2025-01-15 12:00:00" } } } } } ] }, "upi-autopay-2": { "x-schema-group": "Responses", "title": "India UPI Autopay Payment Response", "description": "Response payment object for India UPIAutopay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/in-response-base" }, { "type": "object", "title": "UPI Autopay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "upi-collect-autopay" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" } } } ] }, "payment-response-13": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇮🇳 India", "oneOf": [ { "$ref": "#/components/schemas/card-response-2" }, { "$ref": "#/components/schemas/lrs-travel-2" }, { "$ref": "#/components/schemas/upi-autopay-2" }, { "$ref": "#/components/schemas/upi-3" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "creditcard": "#/components/schemas/card-response-2", "mastercard": "#/components/schemas/card-response-2", "rupay": "#/components/schemas/card-response-2", "visa": "#/components/schemas/card-response-2", "lrs-travel": "#/components/schemas/lrs-travel-2", "upi-collect": "#/components/schemas/upi-3", "upi-collect-autopay": "#/components/schemas/upi-autopay-2", "upi-intent": "#/components/schemas/upi-3", "upi-intent-autopay": "#/components/schemas/upi-autopay-2", "upi-qrcode": "#/components/schemas/upi-3", "upi-qrcode-autopay": "#/components/schemas/upi-autopay-2" } } }, "airtel-2": { "x-schema-group": "Responses", "title": "Kenya Airtel Payment Response", "description": "Response payment object for Kenya Airtel payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Airtel Extra Fields", "properties": { "country": { "type": "string", "example": "ke" }, "currency_ext": { "type": "string", "example": "KES" }, "payment_type_code": { "type": "string", "example": "airtel" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "equitel-2": { "x-schema-group": "Responses", "title": "Kenya Equitel Payment Response", "description": "Response payment object for Kenya Equitel payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Equitel Extra Fields", "properties": { "country": { "type": "string", "example": "ke" }, "currency_ext": { "type": "string", "example": "KES" }, "payment_type_code": { "type": "string", "example": "equitel" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "mobile-money-m-pesa-3": { "x-schema-group": "Responses", "title": "Kenya M-Pesa Payment Response", "description": "Response payment object for Kenya MobileMoneyMPesa payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "type": "object", "title": "Mobile Money M Pesa Extra Fields", "properties": { "country": { "type": "string", "example": "ke" }, "currency_ext": { "type": "string", "example": "KES" }, "payment_type_code": { "type": "string", "example": "mpesa" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "payment-response-14": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇰🇪 Kenya", "oneOf": [ { "$ref": "#/components/schemas/airtel-2" }, { "$ref": "#/components/schemas/equitel-2" }, { "$ref": "#/components/schemas/mobile-money-m-pesa-3" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "airtel": "#/components/schemas/airtel-2", "equitel": "#/components/schemas/equitel-2", "mpesa": "#/components/schemas/mobile-money-m-pesa-3" } } }, "mx-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Mexico Response Base", "properties": { "country": { "type": "string", "example": "mx" }, "currency_ext": { "type": "string", "example": "MXN" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "aplazo-2": { "x-schema-group": "Responses", "title": "Mexico Aplazo Payment Response", "description": "Response payment object for Mexico Aplazo payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/mx-response-base" }, { "type": "object", "title": "Aplazo Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "aplazo" }, "currency_ext_base": { "type": "string", "description": "Base external currency code.\n", "example": "MXN" }, "customer": { "type": "object", "title": "Customer", "description": "Customer information returned in the response.", "properties": { "document": { "type": "string", "description": "Customer's national identification number.", "example": "XAXX010101000" }, "email": { "type": "string", "description": "Customer's email address.", "example": "jose@example.com" }, "name": { "type": "string", "description": "Customer's full name.", "example": "José Silva" }, "birth_date": { "type": "string", "format": "date", "description": "Customer's date of birth.", "example": "1990-03-15" } } } } } ] }, "directdebit-5": { "x-schema-group": "Responses", "title": "Mexico Direct Debit Payment Response", "description": "Response payment object for Mexico Direct Debit payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/mx-response-base" }, { "type": "object", "title": "Directdebit Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "directdebit" } } } ] }, "oxxo-pay-2": { "x-schema-group": "Responses", "title": "Mexico OXXO Pay Payment Response", "description": "Response payment object for Mexico OxxoPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/mx-response-base" }, { "type": "object", "title": "OXXO Pay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "oxxopay" }, "oxxo_url": { "type": "string", "description": "Direct URL for the OXXO payment voucher page.\n", "example": "https://customer.ebanx.com/oxxo/voucher" }, "oxxo_barcode": { "type": "string", "description": "Barcode number for the OXXO payment slip.\n", "example": "78000000000000000000000000000000000000000000000" }, "voucher_url": { "type": "string", "description": "URL to the payment voucher.\n", "example": "https://customer.ebanx.com/voucher" } } } ] }, "paynet-2": { "x-schema-group": "Responses", "title": "Mexico Paynet Payment Response", "description": "Response payment object for Mexico Paynet payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/mx-response-base" }, { "type": "object", "title": "Paynet Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "paynet" }, "voucher_url": { "type": "string", "description": "URL to the Paynet payment voucher.\n", "example": "https://customer.ebanx.com/voucher" } } } ] }, "spei-2": { "x-schema-group": "Responses", "title": "Mexico SPEI Payment Response", "description": "Response payment object for Mexico SPEI payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/mx-response-base" }, { "type": "object", "title": "SPEI Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "spei" }, "clabe_account": { "type": "string", "description": "CLABE account number for SPEI transfer.\n", "example": "646180204800000001" }, "clabe_reference": { "type": "string", "description": "CLABE payment reference number.\n", "example": "1234567" }, "spei_url": { "type": "string", "description": "URL to the SPEI payment voucher.\n", "example": "https://sandbox.ebanxpay.com/spei/voucher" } } } ] }, "payment-response-15": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇲🇽 Mexico", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/aplazo-2" }, { "$ref": "#/components/schemas/directdebit-5" }, { "$ref": "#/components/schemas/mercadopago-response-base" }, { "$ref": "#/components/schemas/mpconnect-response-base" }, { "$ref": "#/components/schemas/oxxo-pay-2" }, { "$ref": "#/components/schemas/paynet-2" }, { "$ref": "#/components/schemas/spei-2" }, { "$ref": "#/components/schemas/stablecoin-response-base" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "carnet": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "aplazo": "#/components/schemas/aplazo-2", "directdebit": "#/components/schemas/directdebit-5", "mercadopago": "#/components/schemas/mercadopago-response-base", "mpconnect": "#/components/schemas/mpconnect-response-base", "mpcredito": "#/components/schemas/mercadopago-response-base", "oxxo": "#/components/schemas/oxxo-pay-2", "oxxopay": "#/components/schemas/oxxo-pay-2", "paynet": "#/components/schemas/paynet-2", "spei": "#/components/schemas/spei-2", "usdc": "#/components/schemas/stablecoin-response-base", "usdt": "#/components/schemas/stablecoin-response-base" } } }, "ng-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Nigeria Response Base", "properties": { "country": { "type": "string", "example": "ng" }, "currency_ext": { "type": "string", "example": "NGN" } } }, "bank-transfer-6": { "x-schema-group": "Responses", "title": "Nigeria Bank Transfer Payment Response", "description": "Response payment object for Nigeria BankTransfer payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ng-response-base" }, { "type": "object", "title": "Bank Transfer Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "banktransfer" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "card-17": { "x-schema-group": "Responses", "title": "Nigeria Card Payment Response", "description": "Response payment object for Nigeria card payments.\n", "allOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/ng-response-base" } ] }, "direct-debit-2": { "x-schema-group": "Responses", "title": "Nigeria Direct Debit Payment Response", "description": "Payment response for Nigerian direct debit one-time and recurring mandates.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ng-response-base" }, { "type": "object", "title": "Nigeria Direct Debit Payment Fields", "properties": { "payment_type_code": { "type": "string", "enum": [ "direct-debit" ], "example": "direct-debit" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to authorize the direct debit mandate. Only present while the mandate awaits authorization.\n", "example": "https://sandbox.ebanxpay.com/ws/redirect?hash=5ae0b5d4f1883ed4b214c0277af29f1981443f59a26eef87" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" } } } ] }, "nibbs-2": { "x-schema-group": "Responses", "title": "Nigeria NIBBS Payment Response", "description": "Response payment object for Nigeria NIBBS payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ng-response-base" }, { "type": "object", "title": "Nibbs Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "nibbs" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "opay-2": { "x-schema-group": "Responses", "title": "Nigeria OPay Payment Response", "description": "Response payment object for Nigeria OPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ng-response-base" }, { "type": "object", "title": "Opay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "opay" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "ussd-2": { "x-schema-group": "Responses", "title": "Nigeria USSD Payment Response", "description": "Response payment object for Nigeria USSD payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ng-response-base" }, { "type": "object", "title": "USSD Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "ussd" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } } ] }, "payment-response-16": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇳🇬 Nigeria", "oneOf": [ { "$ref": "#/components/schemas/bank-transfer-6" }, { "$ref": "#/components/schemas/card-17" }, { "$ref": "#/components/schemas/direct-debit-2" }, { "$ref": "#/components/schemas/nibbs-2" }, { "$ref": "#/components/schemas/opay-2" }, { "$ref": "#/components/schemas/ussd-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "banktransfer": "#/components/schemas/bank-transfer-6", "creditcard": "#/components/schemas/card-17", "debitcard": "#/components/schemas/card-17", "direct-debit": "#/components/schemas/direct-debit-2", "mastercard": "#/components/schemas/card-17", "nibbs": "#/components/schemas/nibbs-2", "opay": "#/components/schemas/opay-2", "ussd": "#/components/schemas/ussd-2", "visa": "#/components/schemas/card-17" } } }, "payment-response-17": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇵🇦 Panama", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "pe-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Peru Response Base", "properties": { "country": { "type": "string", "example": "pe" }, "currency_ext": { "type": "string", "example": "PEN" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "pago-efectivo-2": { "x-schema-group": "Responses", "title": "Peru PagoEfectivo Payment Response", "description": "Response payment object for Peru PagoEfectivo payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/pe-response-base" }, { "type": "object", "title": "PagoEfectivo Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "pagoefectivo" }, "cip_url": { "type": "string", "description": "URL to the CIP payment voucher.\n", "example": "https://customer.ebanx.com/cip" }, "cip_code": { "type": "string", "description": "CIP payment code for PagoEfectivo.\n", "example": "12345678" } } } ] }, "safety-pay-4": { "x-schema-group": "Responses", "title": "Peru SafetyPay Payment Response", "description": "Response payment object for Peru SafetyPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/pe-response-base" }, { "type": "object", "title": "Safety Pay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "safetypay" } } } ] }, "yape-2": { "x-schema-group": "Responses", "title": "Peru Yape Payment Response", "description": "Response payment object for Peru Yape payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/pe-response-base" }, { "type": "object", "title": "Yape Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "yape" } } } ] }, "yape-recurring-2": { "x-schema-group": "Responses", "title": "Peru Yape Recurring Payment Response", "description": "Response payment object for Peru YapeRecurring payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/pe-response-base" }, { "type": "object", "title": "Yape Recurring Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "yape-recurrent" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" } } } ] }, "payment-response-18": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇵🇪 Peru", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/pago-efectivo-2" }, { "$ref": "#/components/schemas/safety-pay-4" }, { "$ref": "#/components/schemas/stablecoin-response-base" }, { "$ref": "#/components/schemas/yape-recurring-2" }, { "$ref": "#/components/schemas/yape-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "pagoefectivo": "#/components/schemas/pago-efectivo-2", "safetypay-cash": "#/components/schemas/safety-pay-4", "safetypay-online": "#/components/schemas/safety-pay-4", "usdc": "#/components/schemas/stablecoin-response-base", "usdt": "#/components/schemas/stablecoin-response-base", "yape": "#/components/schemas/yape-2", "yape-recurrent": "#/components/schemas/yape-recurring-2" } } }, "ph-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Philippines Response Base", "properties": { "country": { "type": "string", "example": "ph" }, "currency_ext": { "type": "string", "example": "PHP" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "g-cash-2": { "x-schema-group": "Responses", "title": "Philippines GCash Payment Response", "description": "Response payment object for Philippines GCash payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ph-response-base" }, { "type": "object", "title": "GCash Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "g-cash" }, "currency_ext_base": { "type": "string", "description": "Base external currency code.\n", "example": "PHP" } } } ] }, "maya-2": { "x-schema-group": "Responses", "title": "Philippines Maya Payment Response", "description": "Response payment object for Philippines Maya payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ph-response-base" }, { "type": "object", "title": "Maya Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "paymaya" }, "currency_ext_base": { "type": "string", "description": "Base external currency code.\n", "example": "PHP" } } } ] }, "qrph-2": { "x-schema-group": "Responses", "title": "Philippines QRPH Payment Response", "description": "Response payment object for Philippines QRPH payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/ph-response-base" }, { "type": "object", "title": "QR Ph Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "qrph" } } } ] }, "payment-response-19": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇵🇭 Philippines", "oneOf": [ { "$ref": "#/components/schemas/g-cash-2" }, { "$ref": "#/components/schemas/maya-2" }, { "$ref": "#/components/schemas/qrph-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "g-cash": "#/components/schemas/g-cash-2", "paymaya": "#/components/schemas/maya-2", "qrph": "#/components/schemas/qrph-2" } } }, "payment-response-20": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇵🇾 Paraguay", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "infonet": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-21": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇸🇻 El Salvador", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "th-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Thailand Response Base", "properties": { "country": { "type": "string", "example": "th" }, "currency_ext": { "type": "string", "example": "THB" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "mobile-banking-2": { "x-schema-group": "Responses", "title": "Thailand Mobile Banking Payment Response", "description": "Response payment object for Thailand Mobile Banking payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/th-response-base" }, { "type": "object", "title": "Mobile Banking Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "mobile-banking" }, "bank_details": { "type": "object", "title": "Bank Details", "description": "Bank selected by the customer for the payment.", "properties": { "bank_code": { "type": "string", "description": "Code of the bank selected by the customer.", "example": "kbank" } } } } } ] }, "promptpay-2": { "x-schema-group": "Responses", "title": "Thailand PromptPay Payment Response", "description": "Response payment object for Thailand PromptPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/th-response-base" }, { "type": "object", "title": "PromptPay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "promptpay" }, "promptpay": { "type": "object", "title": "PromptPay", "description": "PromptPay-specific response data.", "properties": { "qr_code_value": { "type": "string", "description": "QR code value to be rendered for the customer to scan.\n", "example": "00020101021230830016A00000067701011201150107536000315080214KB1023454567890303KB1531340007ANY5303764540599.855802TH6304ABCD" }, "expiration_date": { "allOf": [ { "$ref": "#/components/schemas/not-nullable-datetime" } ], "description": "QR code expiration date/time.\n", "example": "2025-01-15 12:00:00" } } } } } ] }, "payment-response-22": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇹🇭 Thailand", "oneOf": [ { "$ref": "#/components/schemas/mobile-banking-2" }, { "$ref": "#/components/schemas/promptpay-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "mobile-banking": "#/components/schemas/mobile-banking-2", "promptpay": "#/components/schemas/promptpay-2" } } }, "tr-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Turkey Response Base", "properties": { "country": { "type": "string", "example": "tr" }, "currency_ext": { "type": "string", "example": "TRY" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "bank-transfer-7": { "x-schema-group": "Responses", "title": "Turkey Bank Transfer Payment Response", "description": "Response payment object for Turkey Bank Transfer payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/tr-response-base" }, { "type": "object", "title": "Bank Transfer Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "banktransfer" } } } ] }, "payment-response-23": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇹🇷 Turkey", "oneOf": [ { "$ref": "#/components/schemas/bank-transfer-7" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "banktransfer": "#/components/schemas/bank-transfer-7" } } }, "payment-response-24": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇺🇾 Uruguay", "oneOf": [ { "$ref": "#/components/schemas/card-response" }, { "$ref": "#/components/schemas/mercadopago-response-base" }, { "$ref": "#/components/schemas/mpconnect-response-base" }, { "$ref": "#/components/schemas/stablecoin-response-base" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "creditel": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "lider": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "oca": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response", "mercadopago": "#/components/schemas/mercadopago-response-base", "mpconnect": "#/components/schemas/mpconnect-response-base", "mpcredito": "#/components/schemas/mercadopago-response-base", "usdc": "#/components/schemas/stablecoin-response-base", "usdt": "#/components/schemas/stablecoin-response-base" } } }, "vn-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Vietnam Response Base", "properties": { "country": { "type": "string", "example": "vn" }, "currency_ext": { "type": "string", "example": "VND" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/ws/redirect?hash=6564dd1e4b6c3f0a5c1f1e0b1a2c3d4e5f6a7b8c9d0e1f2a" } } }, "vietqr": { "x-schema-group": "Responses", "title": "Vietnam VietQR Payment Response", "description": "Response payment object for Vietnam VietQR payments.\n\nThe customer can complete the payment in three ways:\n- Follow `redirect_url` to the hosted payment page.\n- Scan the QR code rendered by the merchant from `vietqr.qr_code_value`.\n- On mobile, open the customer's banking app with one of the deep links in `vietqr.app_links`.\n", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/vn-response-base" }, { "type": "object", "title": "VietQR Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "vietqr" }, "vietqr": { "type": "object", "title": "VietQR", "description": "VietQR-specific response data. Returned while the payment is not cancelled and the QR code is available.\n", "properties": { "qr_code_value": { "type": "string", "description": "Raw VietQR (EMVCo) payload as text, not an image. Encode it into a QR code image for the customer to scan with Zalopay or a VietQR-enabled banking app.\n", "example": "00020101021238570010A00000072701270006970454011399ZP12345678900208QRIBFTTA530370454065000005802VN6304ABCD" }, "expiration_date": { "allOf": [ { "$ref": "#/components/schemas/not-nullable-datetime" } ], "description": "QR code expiration date/time in the Vietnam local timezone.\n", "example": "2025-01-15 12:15:00" }, "app_links": { "type": "array", "description": "Deep links that open the customer's banking app to pay this order, one per bank.\nEach item is a URI string (e.g. vietinbankipay://... acbone://...)\n", "items": { "type": "string" }, "example": [ "vietinbankipay://host.qrTransfer?order_token=AC8zDc0_06BF-7-7XvRbUNRg" ] } } } } } ] }, "payment-response-25": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇻🇳 Vietnam", "oneOf": [ { "$ref": "#/components/schemas/vietqr" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "vietqr": "#/components/schemas/vietqr" } } }, "za-response-base": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "South Africa Response Base", "properties": { "country": { "type": "string", "example": "za" }, "currency_ext": { "type": "string", "example": "ZAR" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\n", "example": "https://sandbox.ebanxpay.com/redirect/payment" } } }, "capitec-pay-2": { "x-schema-group": "Responses", "title": "South Africa Capitec Pay Payment Response", "description": "Response payment object for South Africa CapitecPay payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/za-response-base" }, { "type": "object", "title": "Capitec Pay Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "capitec-pay" }, "enrollment": { "$ref": "#/components/schemas/enrollment-status-response" }, "subscription": { "$ref": "#/components/schemas/subscription-response" }, "customer": { "type": "object", "title": "Customer", "description": "Customer information returned in the response.", "properties": { "document": { "type": "string", "description": "Customer's document number.", "example": "8501015009087" }, "email": { "type": "string", "description": "Customer's email address.", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "Customer's full name.", "example": "John Doe" }, "birth_date": { "type": "string", "format": "date", "description": "Customer's date of birth.", "example": "1985-01-01" } } } } } ] }, "mobile-money-m-pesa-4": { "x-schema-group": "Responses", "title": "South Africa M-Pesa Payment Response", "description": "Response payment object for South Africa M-Pesa payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/za-response-base" }, { "type": "object", "title": "Mobile Money M Pesa Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "mpesa" } } } ] }, "ozow-2": { "x-schema-group": "Responses", "title": "South Africa Ozow Payment Response", "description": "Response payment object for South Africa Ozow payments.", "allOf": [ { "$ref": "#/components/schemas/payment-response-base" }, { "$ref": "#/components/schemas/za-response-base" }, { "type": "object", "title": "Ozow Extra Fields", "properties": { "payment_type_code": { "type": "string", "example": "ozow" } } } ] }, "payment-response-26": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇿🇦 South Africa", "oneOf": [ { "$ref": "#/components/schemas/capitec-pay-2" }, { "$ref": "#/components/schemas/mobile-money-m-pesa-4" }, { "$ref": "#/components/schemas/ozow-2" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "capitec-pay": "#/components/schemas/capitec-pay-2", "mpesa": "#/components/schemas/mobile-money-m-pesa-4", "ozow": "#/components/schemas/ozow-2" } } }, "payment-response-27": { "x-hidden": true, "x-schema-group": "Responses", "title": "Payment Response", "description": "The payment response object. Structure varies by country and payment method.\nShared between the Direct (create) and Query endpoints.\n", "oneOf": [ { "$ref": "#/components/schemas/payment-response" }, { "$ref": "#/components/schemas/payment-response-2" }, { "$ref": "#/components/schemas/payment-response-3" }, { "$ref": "#/components/schemas/payment-response-4" }, { "$ref": "#/components/schemas/payment-response-5" }, { "$ref": "#/components/schemas/payment-response-6" }, { "$ref": "#/components/schemas/payment-response-7" }, { "$ref": "#/components/schemas/payment-response-8" }, { "$ref": "#/components/schemas/payment-response-9" }, { "$ref": "#/components/schemas/payment-response-10" }, { "$ref": "#/components/schemas/payment-response-11" }, { "$ref": "#/components/schemas/payment-response-12" }, { "$ref": "#/components/schemas/payment-response-13" }, { "$ref": "#/components/schemas/payment-response-14" }, { "$ref": "#/components/schemas/payment-response-15" }, { "$ref": "#/components/schemas/payment-response-16" }, { "$ref": "#/components/schemas/payment-response-17" }, { "$ref": "#/components/schemas/payment-response-18" }, { "$ref": "#/components/schemas/payment-response-20" }, { "$ref": "#/components/schemas/payment-response-21" }, { "$ref": "#/components/schemas/payment-response-19" }, { "$ref": "#/components/schemas/payment-response-22" }, { "$ref": "#/components/schemas/payment-response-23" }, { "$ref": "#/components/schemas/payment-response-24" }, { "$ref": "#/components/schemas/payment-response-25" }, { "$ref": "#/components/schemas/payment-response-26" } ], "discriminator": { "propertyName": "country", "mapping": { "ar": "#/components/schemas/payment-response", "bo": "#/components/schemas/payment-response-2", "br": "#/components/schemas/payment-response-3", "cl": "#/components/schemas/payment-response-4", "co": "#/components/schemas/payment-response-5", "cr": "#/components/schemas/payment-response-6", "do": "#/components/schemas/payment-response-7", "ec": "#/components/schemas/payment-response-8", "eg": "#/components/schemas/payment-response-9", "gh": "#/components/schemas/payment-response-10", "gt": "#/components/schemas/payment-response-11", "id": "#/components/schemas/payment-response-12", "in": "#/components/schemas/payment-response-13", "ke": "#/components/schemas/payment-response-14", "mx": "#/components/schemas/payment-response-15", "ng": "#/components/schemas/payment-response-16", "pa": "#/components/schemas/payment-response-17", "pe": "#/components/schemas/payment-response-18", "ph": "#/components/schemas/payment-response-19", "py": "#/components/schemas/payment-response-20", "sv": "#/components/schemas/payment-response-21", "th": "#/components/schemas/payment-response-22", "tr": "#/components/schemas/payment-response-23", "uy": "#/components/schemas/payment-response-24", "vn": "#/components/schemas/payment-response-25", "za": "#/components/schemas/payment-response-26" } } }, "customization-extras": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Merchant Customization Extras", "description": "Top-level payment response fields that are injected only for specific merchants via\nmerchant-customization morphers. They are not part of the public contract and are hidden\nfrom the public documentation. Present only for the relevant merchant.\n", "properties": null }, "customer": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "nullable": true, "title": "Customer", "description": "Customer information associated with the payment.\n", "properties": { "document": { "type": "string", "description": "Customer's national identification number as provided in the request.\n", "example": "853.513.468-93" }, "email": { "type": "string", "format": "email", "description": "Customer email address.\n", "example": "jose@example.com" }, "name": { "type": "string", "description": "Customer name.\n", "example": "José Silva" }, "birth_date": { "type": "string", "format": "date", "nullable": true, "description": "Customer birth date.\n", "example": "1990-03-15" } } }, "direct-response": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Direct Response", "description": "The response parameters will vary depending on the chosen payment method.\n", "properties": { "status": { "type": "string", "description": "The status of the request (`SUCCESS` or `ERROR`).\n", "example": "SUCCESS", "minLength": 5, "maxLength": 7 }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to redirect the customer to complete the payment.\nCopied from `payment.redirect_url` for convenience. Only present for payment methods that require customer redirection.\n", "example": "https://sandbox.ebanxpay.com/ws/redirect?hash=abc123" }, "payment": { "description": "The payment response object. Structure varies by country and payment method.", "x-default-expanded": false, "allOf": [ { "$ref": "#/components/schemas/payment-response-27" }, { "$ref": "#/components/schemas/customization-extras" }, { "type": "object", "title": "Direct Response Extra Fields", "properties": { "customer": { "$ref": "#/components/schemas/customer" } } } ] } } }, "payments-error-code": { "title": "Payment Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Core payment validation error codes returned by the Direct Payment API.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-0" ], "description": "Payment already exists with the same merchant_payment_code." }, { "enum": [ "BP-DR-2" ], "description": "Field `payment` is required." }, { "enum": [ "BP-DR-3" ], "description": "Field `payment.currency_code` is required." }, { "enum": [ "BP-DR-5" ], "description": "Field `payment.amount_total` is required." }, { "enum": [ "BP-DR-6" ], "description": "Amount reported is less than the minimum amount or violates currency-specific rules." }, { "enum": [ "BP-DR-7" ], "description": "Amount must be less than the maximum allowed." }, { "enum": [ "BP-DR-8" ], "description": "Fields `amount_items` + `amount_shipping` must be equal to `amount_total`." }, { "enum": [ "BP-DR-9" ], "description": "Field `payment.merchant_payment_code` is required or `payment_type_code` is invalid." }, { "enum": [ "BP-DR-10" ], "description": "Parameter `merchant_payment_code` can have 40 characters maximum." }, { "enum": [ "BP-DR-11" ], "description": "Parameter `payment.order_number` can have 40 characters maximum." }, { "enum": [ "BP-DR-12" ], "description": "Parameter exceeds maximum character length." }, { "enum": [ "BP-DR-30" ], "description": "Field `payment.amount_total` is not a valid number." }, { "enum": [ "BP-DR-35" ], "description": "The provided `payment_type_code` is invalid." }, { "enum": [ "BP-DR-36" ], "description": "Payment type is not active." }, { "enum": [ "BP-DR-38" ], "description": "Payment type not allowed in Direct API (full mode)." }, { "enum": [ "BP-DR-41" ], "description": "Field `payment.person_type` must contain a valid `person_type`." }, { "enum": [ "BP-DR-50" ], "description": "Field `payment.merchant_payment_code` or `payment.order_number` must contain valid characters." }, { "enum": [ "BP-DR-57" ], "description": "Parameter is in an invalid format (`due_date`)." }, { "enum": [ "BP-DR-58" ], "description": "Parameter `due_date` exceeds more than the configured number of days." }, { "enum": [ "BP-DR-59" ], "description": "Parameter `due_date` is less than permitted." }, { "enum": [ "BP-DR-77" ], "description": "Country is not enabled." }, { "enum": [ "BP-DR-78" ], "description": "Country or payment type not enabled for merchant." }, { "enum": [ "BP-DR-81" ], "description": "The `currency_code` is not allowed for `payment_type_code`." }, { "enum": [ "BP-DR-82" ], "description": "Parameter `payment.note` can have 200 characters maximum." }, { "enum": [ "BP-DR-84" ], "description": "Duplicate payment for the same customer and amount within configured minutes." }, { "enum": [ "BP-DR-90" ], "description": "The card or customer is in the blocklist for legal reasons." }, { "enum": [ "BP-DR-102" ], "description": "Too many attempts." }, { "enum": [ "BP-DR-113" ], "description": "Invalid transaction (card pre-validation failure or CPF blocklist)." }, { "enum": [ "BP-DR-114" ], "description": "Transaction declined: customer CPF blocked for fraud (PIX)." }, { "enum": [ "BP-DR-116" ], "description": "Merchant not enabled for Manual Review." }, { "enum": [ "BP-DR-140" ], "description": "Affiliation ID is required for this payment type." }, { "enum": [ "BP-DR-151" ], "description": "Payment is not eligible for this flow." }, { "enum": [ "BP-DR-170" ], "description": "Split payment is required for this merchant and payment type configuration." }, { "enum": [ "BP-DR-173" ], "description": "Field `payment.amount_total` cannot contain commas." }, { "enum": [ "BP-DR-183" ], "description": "Field `payment.currency_rate_usd` not allowed for this merchant." }, { "enum": [ "BP-DR-184" ], "description": "Field `payment.currency_rate_usd` cannot contain commas." }, { "enum": [ "BP-DR-185" ], "description": "Field `payment.currency_rate_usd` is invalid." }, { "enum": [ "BP-DR-186" ], "description": "Trusted transaction info should be a boolean." }, { "enum": [ "BP-DR-188" ], "description": "Field `payment.iof_paid_by_merchant` is invalid." }, { "enum": [ "BP-DR-189" ], "description": "Field `payment.iof_paid_by_merchant` must be a boolean." }, { "enum": [ "BP-DR-205" ], "description": "Parameter `payment.merchant_associated_invoices` can have 2550 characters maximum." }, { "enum": [ "BP-DR-206" ], "description": "Parameter `payment.info_to_payer` can have 140 characters maximum." }, { "enum": [ "BP-DR-215" ], "description": "The `currency_code` is not allowed for the `country` for this merchant." }, { "enum": [ "BP-DR-219" ], "description": "Enrollment is not supported for this payment type." }, { "enum": [ "BP-IP-001" ], "description": "Parameter `payment.installments_plan_token` is required." }, { "enum": [ "BP-IP-002" ], "description": "Parameter `payment.installments_plan_token` is invalid or does not belong to the merchant." }, { "enum": [ "BP-IP-003" ], "description": "The `installments_plan_token` is expired." }, { "enum": [ "BP-IP-004" ], "description": "Provided country must be equal to the installments plan country." }, { "enum": [ "BP-IP-005" ], "description": "Provided currency code must be equal to the installments plan currency." }, { "enum": [ "BP-IP-006" ], "description": "Provided amount must be equal to the installments plan amount." }, { "enum": [ "BP-IP-007" ], "description": "Provided payment type code must be equal to the installments plan payment type." }, { "enum": [ "BP-IP-008" ], "description": "Provided installments value is not available in the installments plan." }, { "enum": [ "BP-IP-009" ], "description": "Country or payment type group is not valid for the installments plan." }, { "enum": [ "BP-UE-03" ], "description": "Merchant enrollment code is missing for recurrent payment." }, { "enum": [ "BP-UE-12" ], "description": "Unexpected error during enrollment." }, { "enum": [ "BP-UE-32" ], "description": "Provider internal server error during enrollment." }, { "enum": [ "BP-UE-33" ], "description": "External service not available during enrollment (timeout)." }, { "enum": [ "BP-UE-36" ], "description": "User enrollment subscription amount conflicts with the payment amount." }, { "enum": [ "BP-ENC-02" ], "description": "Card data encrypted with JWE is invalid or cannot be decrypted." }, { "enum": [ "BP-REF-15" ], "description": "Invalid operation for this payment type or environment." }, { "enum": [ "BP-DR-60" ], "description": "Invalid merchant_enrollment_code for pix-automatico." }, { "enum": [ "BP-DR-182" ], "description": "Enrollment is not accepted, cannot transact." }, { "enum": [ "BP-DR-999" ], "description": "Hard decline propagated from cross-border payment processing." }, { "enum": [ "BP-R-5" ], "description": "Payment has an attempt being processed." }, { "enum": [ "BP-R-6" ], "description": "Payment has no available retries." }, { "enum": [ "BP-GP-2" ], "description": "Invalid Google Pay payload." }, { "enum": [ "BP-ST-00" ], "description": "Single Transaction not enabled for merchant." }, { "enum": [ "BP-ST-01" ], "description": "Single Transaction is only available for the EBANX Local environment." }, { "enum": [ "BP-ST-02" ], "description": "The single_transaction parameter is missing." }, { "enum": [ "BP-ST-03" ], "description": "The amount_local parameter is null." }, { "enum": [ "BP-ST-04" ], "description": "The amount_crossborder parameter is null." }, { "enum": [ "BP-ST-05" ], "description": "The request amount_local and amount_crossborder sum exceeds the total amount." }, { "enum": [ "BP-ST-06" ], "description": "The request amount_local and amount_crossborder sum is less than the total amount." }, { "enum": [ "BP-ST-13" ], "description": "Single transaction amounts should not be negative." }, { "enum": [ "BP-TX-01" ], "description": "The parameter taxes is null for a single transaction with local amount." }, { "enum": [ "BP-TX-02" ], "description": "The parameter iva_co is null." }, { "enum": [ "BP-TX-03" ], "description": "The parameter iva_co should be a valid number." }, { "enum": [ "BP-DOC-01" ], "description": "Invalid customer document." }, { "enum": [ "BP-DR-600" ], "description": "Customer document is disabled on EBANX due to too many attempts by payment type." }, { "enum": [ "BP-DR-601" ], "description": "Customer email is disabled on EBANX due to too many attempts by payment type." }, { "enum": [ "BP-DR-602" ], "description": "Declined transaction with amount above limit." }, { "enum": [ "BP-DR-603" ], "description": "Customer phone number is in the blocklist." } ], "example": "BP-DR-35" }, "customer-error-code": { "title": "Customer Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes related to customer data validation in the Direct Payment API.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-13" ], "description": "Field `payment.name` is required." }, { "enum": [ "BP-DR-14" ], "description": "Parameter `payment.name` can have 100 characters maximum." }, { "enum": [ "BP-DR-15" ], "description": "Field `payment.email` is required." }, { "enum": [ "BP-DR-16" ], "description": "Parameter `payment.email` can have 100 characters maximum." }, { "enum": [ "BP-DR-17" ], "description": "Field `payment.email` must be a valid email." }, { "enum": [ "BP-DR-18" ], "description": "Customer is disabled on EBANX." }, { "enum": [ "BP-DR-20" ], "description": "Field `payment.birth_date` must be a valid birth date (dd/MM/yyyy)." }, { "enum": [ "BP-DR-21" ], "description": "Customer must be at least 16 years old." }, { "enum": [ "BP-DR-22" ], "description": "Field `payment.document` is required." }, { "enum": [ "BP-DR-23" ], "description": "Field `payment.document` must be a valid document." }, { "enum": [ "BP-DR-24" ], "description": "Field `payment.zipcode` is required." }, { "enum": [ "BP-DR-25" ], "description": "Field `payment.address` is required or must be a valid address." }, { "enum": [ "BP-DR-26" ], "description": "Field `payment.street_number` is required." }, { "enum": [ "BP-DR-27" ], "description": "Field `payment.city` is required." }, { "enum": [ "BP-DR-28" ], "description": "Field `payment.state` is required." }, { "enum": [ "BP-DR-29" ], "description": "Field `payment.state` must be a valid state code." }, { "enum": [ "BP-DR-31" ], "description": "Field `payment.phone_number` is required." }, { "enum": [ "BP-DR-32" ], "description": "Parameter `payment.phone_number` must be a valid phone number." }, { "enum": [ "BP-DR-39" ], "description": "CPF, name, and birth date do not match." }, { "enum": [ "BP-DR-40" ], "description": "This payment exceeds the maximum amount per month or per payment for this customer." }, { "enum": [ "BP-DR-42" ], "description": "Field `payment.responsible` is required (company payments)." }, { "enum": [ "BP-DR-43" ], "description": "Field `payment.responsible.name` is required." }, { "enum": [ "BP-DR-44" ], "description": "Field `payment.responsible.document` is required." }, { "enum": [ "BP-DR-45" ], "description": "Field `payment.responsible.birth_date` is required." }, { "enum": [ "BP-DR-46" ], "description": "Company responsible's CPF, name, and birthdate do not match." }, { "enum": [ "BP-DR-98" ], "description": "Customer e-mail is associated with payments for a different country." }, { "enum": [ "BP-DR-103" ], "description": "Customer temporarily inactivated (excessive number of credit cards)." }, { "enum": [ "BP-DR-111" ], "description": "Customer document could not be validated." }, { "enum": [ "BP-DR-141" ], "description": "The `document_country` provided is not a valid country." }, { "enum": [ "BP-DR-142" ], "description": "Merchant is not authorized to process transactions with foreign customers." }, { "enum": [ "BP-DR-166" ], "description": "Invalid zipcode format (must contain exactly 6 digits, India-specific)." }, { "enum": [ "BP-DR-211" ], "description": "The `customer_device_info.source` field is invalid." } ], "example": "BP-DR-22" }, "general-error-code": { "title": "General Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "General error codes specific to the Direct Payment API, including currency errors, external service failures,\nand payment processing errors.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-4" ], "description": "Currency is not active in the system or conversion not available." }, { "enum": [ "BP-DR-104" ], "description": "Invalid `notification_url`." }, { "enum": [ "BP-DR-107" ], "description": "Timeout on communicating with external API(s)." }, { "enum": [ "BP-DR-108" ], "description": "Invalid FX Token." }, { "enum": [ "BP-DR-109" ], "description": "FX Token not enabled." }, { "enum": [ "BP-DR-110" ], "description": "FX Token currency not enabled or not found." }, { "enum": [ "BP-DR-119" ], "description": "Timeout on communicating with external API(s) during payment processing." }, { "enum": [ "BP-DR-120" ], "description": "External service not available." }, { "enum": [ "BP-DR-121" ], "description": "External service unavailable during payment creation or FX." }, { "enum": [ "BP-DR-143" ], "description": "Hard decline from e-wallet provider." }, { "enum": [ "BP-DR-144" ], "description": "Unable to process payment. Try again later." }, { "enum": [ "BP-DR-164" ], "description": "JWE integration key error." }, { "enum": [ "BP-DR-187" ], "description": "Payment creation error." } ], "example": "BP-DR-4" }, "payment-method-error-code": { "title": "Payment Method Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to individual payment methods in the Direct Payment API.\nIncludes direct debit, bank transfer, PIX, boleto, PSE/ACH, and other method-specific validations.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-37" ], "description": "The `amount_total` does not match the enrollment `fixed_amount` (PIX Automatico)." }, { "enum": [ "BP-DR-47" ], "description": "Parameter `payment.directdebit.bank_account` can have 10 characters maximum." }, { "enum": [ "BP-DR-62" ], "description": "Subscription cycle already has one payment (PIX Automatico)." }, { "enum": [ "BP-DR-63" ], "description": "Payment `due_date` is before the subscription start date." }, { "enum": [ "BP-DR-68" ], "description": "Field `payment.directdebit.bank_account` is required." }, { "enum": [ "BP-DR-69" ], "description": "Parameter `payment.directdebit.bank_agency` can have 10 characters maximum." }, { "enum": [ "BP-DR-70" ], "description": "Field `payment.directdebit.bank_agency` is required." }, { "enum": [ "BP-DR-71" ], "description": "Parameter `payment.directdebit.bank_code` can have 5 characters maximum." }, { "enum": [ "BP-DR-72" ], "description": "Field `payment.directdebit.bank_code` is required." }, { "enum": [ "BP-DR-73" ], "description": "Field `payment.directdebit` is required for this payment type." }, { "enum": [ "BP-DR-76" ], "description": "Object `payment.bank_details` or `bank_details.bank_code` is required for this payment type." }, { "enum": [ "BP-DR-80" ], "description": "It was not possible to generate CIP (PagoEfectivo)." }, { "enum": [ "BP-DR-91" ], "description": "Field `bank_code` is required or invalid for ACH/PSE and DuitNow payments." }, { "enum": [ "BP-DR-92" ], "description": "Field `payment.institution_code` is not a valid bank code." }, { "enum": [ "BP-DR-93" ], "description": "Error creating this payment within PSE ACH." }, { "enum": [ "BP-DR-105" ], "description": "Parameter `payment.flow_payment_method` is required (Flow)." }, { "enum": [ "BP-DR-128" ], "description": "Boleto BEXS is not available." }, { "enum": [ "BP-DR-150" ], "description": "PIX expiration time error." }, { "enum": [ "BP-DR-171" ], "description": "Local amount override error." }, { "enum": [ "BP-DR-172" ], "description": "Field `payment.bank_details.account_number` is required for this payment type." }, { "enum": [ "BP-DR-174" ], "description": "Field `payment.metadata.upi_vpa` is required for UPI payments." }, { "enum": [ "BP-DR-180" ], "description": "The `merchant_enrollment_code` was not found." }, { "enum": [ "BP-DR-181" ], "description": "Enrollment event not found." }, { "enum": [ "BP-DR-191" ], "description": "HSN Code validation error (India-specific)." }, { "enum": [ "BP-DR-207" ], "description": "The customer was not notified (enrollment pre-charge)." }, { "enum": [ "BP-DR-208" ], "description": "Invalid `integration_key` (token delete)." }, { "enum": [ "BP-DR-209" ], "description": "Token not found (token delete)." }, { "enum": [ "BP-DR-210" ], "description": "The `merchant_enrollment_code` is required." }, { "enum": [ "BP-DR-213" ], "description": "Field `metadata.lrs_type` is required for LRS travel payments." }, { "enum": [ "BP-DR-214" ], "description": "Field `metadata.lrs_type` has an incorrect value (`flight`, `hotel` or `tour`)." }, { "enum": [ "BP-DR-216" ], "description": "Payment country mismatch with enrollment country." }, { "enum": [ "BP-DR-220" ], "description": "The enrollment is single-use (one-time) and cannot be reused for a new payment." } ], "example": "BP-DR-91" }, "sub-account-error-code": { "title": "Sub-Account Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes related to sub-account validation in the Direct Payment API.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-85" ], "description": "Field `payment.sub_account` is required." }, { "enum": [ "BP-DR-86" ], "description": "Parameter is invalid for `payment.sub_account`." }, { "enum": [ "BP-DR-87" ], "description": "Field `payment.sub_account.name` is required." }, { "enum": [ "BP-DR-88" ], "description": "Field `payment.sub_account.image_url` is required when informed." }, { "enum": [ "BP-DR-99" ], "description": "Field `payment.sub_account.image_url` must be https." }, { "enum": [ "BP-DR-118" ], "description": "Invalid Sub Account data." }, { "enum": [ "BP-DR-175" ], "description": "Field `payment.sub_account.code` is required." }, { "enum": [ "BP-DR-200" ], "description": "Sub-account legal name validation error (FlyWire)." }, { "enum": [ "BP-DR-203" ], "description": "Sub-account country validation error (FlyWire)." }, { "enum": [ "BP-DR-204" ], "description": "Sub-account is missing (FlyWire)." } ], "example": "BP-DR-85" }, "api-error-code": { "title": "API Error Codes", "x-schema-group": "Shared", "type": "string", "description": "General error codes shared across all EBANX API endpoints (ws/direct, ws/token, ws/capture, ws/request, etc.).\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "DA-0" ], "description": "Unknown error." }, { "enum": [ "DA-1" ], "description": "Empty operation parameter or invalid JSON." }, { "enum": [ "DA-3" ], "description": "Rate limiting — too many requests. Try again later." }, { "enum": [ "BP-DPAR-1" ], "description": "Request body is empty." }, { "enum": [ "BP-DPAR-2" ], "description": "Invalid JSON expression." }, { "enum": [ "BP-DPAR-3" ], "description": "Field integration_key is required." }, { "enum": [ "BP-DPAR-4" ], "description": "Invalid integration key." }, { "enum": [ "BP-DPAR-5" ], "description": "Merchant account is not active." }, { "enum": [ "BP-DPAR-6" ], "description": "This merchant account is restricted to testing." }, { "enum": [ "BP-DPAR-7" ], "description": "This merchant account cannot be used for testing." } ], "example": "DA-0" }, "auth-error-code": { "title": "Authentication Error Code", "x-schema-group": "Shared", "type": "string", "description": "Authentication error codes returned by all endpoints that require merchant authentication via integration key.\n", "oneOf": [ { "enum": [ "BP-SA-1" ], "description": "Parameter integration_key was not provided in the request." }, { "enum": [ "BP-SA-2" ], "description": "The integration key provided is invalid or does not match any merchant account." }, { "enum": [ "BP-SA-3" ], "description": "The merchant account associated with the integration key is not active." }, { "enum": [ "BP-SA-4" ], "description": "A test/sandbox merchant account was used against the production environment." }, { "enum": [ "BP-SA-5" ], "description": "A production merchant account was used against the sandbox/test environment." } ], "example": "BP-SA-2" }, "apm-error-response": { "x-schema-group": "Shared", "title": "APM Payment Error Response", "type": "object", "description": "Error response returned when an APM (non-card) payment request fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/payments-error-code" }, { "$ref": "#/components/schemas/customer-error-code" }, { "$ref": "#/components/schemas/general-error-code" }, { "$ref": "#/components/schemas/payment-method-error-code" }, { "$ref": "#/components/schemas/sub-account-error-code" }, { "$ref": "#/components/schemas/api-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code. Includes Payments, Customer, General, Payment Method, Sub-Account, Authentication, and API-wide error codes.\n", "example": "BP-DR-17" }, "status_message": { "type": "string", "description": "A human-readable error message describing what went wrong.\n", "example": "Parameter payment.name is required and was not informed" } } }, "cards-error-code": { "title": "Cards Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to credit and debit card transactions in the Direct Payment API.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-33" ], "description": "Invalid value for instalments (single value)." }, { "enum": [ "BP-DR-34" ], "description": "Invalid value for instalments (range)." }, { "enum": [ "BP-DR-48" ], "description": "Field `payment.card` is required for this payment type." }, { "enum": [ "BP-DR-49" ], "description": "Field `payment.card.card_number` is required." }, { "enum": [ "BP-DR-51" ], "description": "Field `payment.card.card_name` is required." }, { "enum": [ "BP-DR-53" ], "description": "The `card_cvv_mode` field only accepts `recurrent` or `provided` as values." }, { "enum": [ "BP-DR-54" ], "description": "Field `payment.card.card_cvv` is required." }, { "enum": [ "BP-DR-55" ], "description": "Parameter `payment.card.card_cvv` is invalid (max 4 characters)." }, { "enum": [ "BP-DR-56" ], "description": "Field `payment.card.card_due_date` is required." }, { "enum": [ "BP-DR-61" ], "description": "It was not possible to create the token for this credit card." }, { "enum": [ "BP-DR-64" ], "description": "Token not found." }, { "enum": [ "BP-DR-65" ], "description": "The provided token is already in use." }, { "enum": [ "BP-DR-66" ], "description": "Token not valid (length must be between 32 and 128 characters)." }, { "enum": [ "BP-DR-67" ], "description": "Field `payment.card.card_due_date` is invalid, token is expired, or card is invalid." }, { "enum": [ "BP-DR-75" ], "description": "Card number is invalid." }, { "enum": [ "BP-DR-79" ], "description": "The amount of instalments is larger than the maximum allowed." }, { "enum": [ "BP-DR-83" ], "description": "Foreign credit card cannot be processed." }, { "enum": [ "BP-DR-89" ], "description": "The amount of instalments is not allowed (blocked values)." }, { "enum": [ "BP-DR-95" ], "description": "Parameter `payment.card.card_name` must be a valid name." }, { "enum": [ "BP-DR-96" ], "description": "Token expired." }, { "enum": [ "BP-DR-97" ], "description": "Instalment payments are not allowed for prepaid cards." }, { "enum": [ "BP-DR-100" ], "description": "Instalment payments are not allowed for debit cards." }, { "enum": [ "BP-DR-101" ], "description": "Card is not eligible for ecommerce." }, { "enum": [ "BP-DR-112" ], "description": "Too many attempts resulting in Insufficient Funds for this card." }, { "enum": [ "BP-DR-117" ], "description": "Value per instalment cannot be lower than R$5.00." }, { "enum": [ "BP-DR-129" ], "description": "Payments with instalments must be made with auto-capture mode enabled." }, { "enum": [ "BP-DR-176" ], "description": "Card verification is not enabled for this merchant." } ], "example": "BP-DR-75" }, "network-token-error-code": { "title": "Network Token Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to network token operations in the Direct Payment API.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-135" ], "description": "The `network_token_pan` is invalid." }, { "enum": [ "BP-DR-136" ], "description": "The `network_token_expire_date` is invalid." }, { "enum": [ "BP-DR-137" ], "description": "The `network_token_cryptogram` is invalid." }, { "enum": [ "BP-DR-147" ], "description": "The `network_token_raw_bin` is invalid." }, { "enum": [ "BP-DR-148" ], "description": "The `network_token_raw_last4` is invalid." }, { "enum": [ "BP-DR-177" ], "description": "The `network_token_wallet_type` value is not allowed." }, { "enum": [ "BP-DR-178" ], "description": "Field `payment.card.network_token_wallet_type` is required." }, { "enum": [ "BP-DR-190" ], "description": "The `network_token_eci` is invalid." } ], "example": "BP-DR-135" }, "3ds-error-code": { "title": "3DS 2.0 Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to 3D Secure 2.0 authentication in the Direct Payment API.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-3DS-1" ], "description": "Parameter `public_integration_key` not informed." }, { "enum": [ "BP-3DS-2" ], "description": "Invalid public integration key." }, { "enum": [ "BP-3DS-19" ], "description": "The `threeds_mode` and `threeds_force` parameters are mutually exclusive." }, { "enum": [ "BP-3DS-20" ], "description": "The provided `threeds_mode` value is not valid." }, { "enum": [ "BP-3DS-33" ], "description": "The `browser_info.color_depth` field must be a string." }, { "enum": [ "BP-3DS-34" ], "description": "The `browser_info.screen_height` field is required for `data_only` 3DS mode." }, { "enum": [ "BP-3DS-35" ], "description": "The `browser_info.screen_height` field must be a string." }, { "enum": [ "BP-3DS-36" ], "description": "The `browser_info.screen_width` field is required for `data_only` 3DS mode." }, { "enum": [ "BP-3DS-37" ], "description": "The `browser_info.screen_width` field must be a string." }, { "enum": [ "BP-3DS-38" ], "description": "The `browser_info.timezone_offset` field is required for `data_only` 3DS mode." }, { "enum": [ "BP-3DS-39" ], "description": "The `browser_info.timezone_offset` field must be a string." }, { "enum": [ "BP-3DS-40" ], "description": "The `browser_info.javascript_enabled` field is required for `data_only` 3DS mode." }, { "enum": [ "BP-3DS-41" ], "description": "The `browser_info.javascript_enabled` field must be a boolean." }, { "enum": [ "BP-3DS-42" ], "description": "The `browser_info.java_enabled` field is required for `data_only` 3DS mode." }, { "enum": [ "BP-3DS-43" ], "description": "The `browser_info.java_enabled` field must be a boolean." }, { "enum": [ "BP-3DS-44" ], "description": "The `browser_info` object is required when using `data_only` or `data_only_preferred` 3DS mode." }, { "enum": [ "BP-3DS-45" ], "description": "The 3DS UCAF (Universal Cardholder Authentication Field) was already used for another payment." }, { "enum": [ "BP-3DS-46" ], "description": "The 3DS authentication data (ECI/XID) sent in the payment request does not match the authentication data stored by EBANX, or the 3DS authentication reference could not be resolved." }, { "enum": [ "BP-DR-130" ], "description": "Field `payment.card.threeds_cryptogram` is required." }, { "enum": [ "BP-DR-131" ], "description": "Field `payment.card.threeds_eci` is required." }, { "enum": [ "BP-DR-133" ], "description": "Both `threeds_cryptogram` and `threeds_eci` must be provided together." }, { "enum": [ "BP-DR-138" ], "description": "Parameter `payment.card.threeds_trxid` is mandatory for 3DS Data Only." }, { "enum": [ "BP-DR-139" ], "description": "Parameter `payment.card.threeds_version` is invalid (valid values are `1` or `2`)." }, { "enum": [ "BP-DR-145" ], "description": "The card BIN is not supported for 3D Secure authentication." }, { "enum": [ "BP-DR-146" ], "description": "3DS cannot be forced for a notified enrollment charge." } ], "example": "BP-3DS-1" }, "cof-error-code": { "title": "COF Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes returned when Card-on-File (COF) parameter validation fails.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-DR-152" ], "description": "The `cof_type` field is required but was not provided." }, { "enum": [ "BP-DR-153" ], "description": "The provided `cof_type` value is not one of the allowed values." }, { "enum": [ "BP-DR-154" ], "description": "The `initiator` field is required but was not provided." }, { "enum": [ "BP-DR-155" ], "description": "The provided `initiator` value is not one of the allowed values." }, { "enum": [ "BP-DR-156" ], "description": "The `trans_type` field is required but was not provided." }, { "enum": [ "BP-DR-157" ], "description": "The provided `trans_type` value is not one of the allowed values." }, { "enum": [ "BP-DR-158" ], "description": "Merchant-initiated transactions cannot use `cof_type` initial. Only customer-initiated transactions can establish a new card-on-file agreement." }, { "enum": [ "BP-DR-167" ], "description": "Customer-initiated transactions cannot set up an initial MERCHANT_COF agreement." }, { "enum": [ "BP-DR-168" ], "description": "Merchant-initiated transactions cannot use CUSTOMER_COF as the transaction type." }, { "enum": [ "BP-DR-169" ], "description": "Customer-initiated stored transactions must use CUSTOMER_COF as the transaction type." } ], "example": "BP-DR-152" }, "card-error-response": { "x-schema-group": "Shared", "title": "Card Payment Error Response", "type": "object", "x-payment-variants": [ "Card Payment", "Card", "Card Recurring" ], "description": "Error response returned when a credit or debit card payment request fails. Includes card-specific and 3DS 2.0 error codes in addition to general errors.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/payments-error-code" }, { "$ref": "#/components/schemas/customer-error-code" }, { "$ref": "#/components/schemas/general-error-code" }, { "$ref": "#/components/schemas/cards-error-code" }, { "$ref": "#/components/schemas/network-token-error-code" }, { "$ref": "#/components/schemas/3ds-error-code" }, { "$ref": "#/components/schemas/cof-error-code" }, { "$ref": "#/components/schemas/api-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code. Includes Payments, Customer, General, Cards, Network Token, 3DS 2.0, COF, Authentication, and API-wide error codes.\n", "example": "BP-DR-33" }, "status_message": { "type": "string", "description": "A human-readable error message describing what went wrong.\n", "example": "Credit card number is not valid" } } }, "query-request": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Query Request", "description": "The query operation is a server-to-server HTTP POST used by the merchant website to query EBANX for information about a specific payment.\n", "properties": { "hash": { "type": "string", "description": "The payment hash (EBANX unique identifier).\n", "x-conditional": "Required if merchant_payment_code is not provided", "minLength": 48, "maxLength": 48, "example": "5478ba283ef8674415082844ee14817376e49bb76aa9d4c7" }, "merchant_payment_code": { "type": "string", "description": "The payment hash Merchant Payment Code (unique merchant ID).\n", "x-conditional": "Required if hash is not provided", "minLength": 1, "maxLength": 40, "example": "1416854121" } }, "anyOf": [ { "required": [ "hash" ] }, { "required": [ "merchant_payment_code" ] } ] }, "query-customer": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "nullable": true, "title": "Query Customer", "description": "Customer information in the query response. Extends the shared customer object\nwith address and contact fields that are returned exclusively by the query endpoint.\n", "allOf": [ { "$ref": "#/components/schemas/customer" }, { "type": "object", "title": "Query Customer Extra Fields", "properties": { "address": { "type": "string", "nullable": true, "description": "Customer street address.\n", "example": "Rua E" }, "street_number": { "type": "string", "nullable": true, "description": "Customer street number.\n", "example": "1040" }, "street_complement": { "type": "string", "nullable": true, "description": "Additional address information (apartment, suite, floor, etc.).\n", "example": "Apto 101" }, "city": { "type": "string", "nullable": true, "description": "Customer city.\n", "example": "Maringá" }, "state": { "type": "string", "nullable": true, "description": "Customer state or province code.\n", "example": "PR" }, "zipcode": { "type": "string", "nullable": true, "description": "Customer postal/ZIP code.\n", "example": "87020-020" }, "country": { "type": "string", "description": "Customer country code (ISO 3166-1 alpha-2).\n", "example": "br" }, "phone_number": { "type": "string", "nullable": true, "description": "Customer phone number.\n", "example": "5511999999999" } } } ] }, "customer-bank-info-status": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Customer Bank Info Status", "description": "Information about the status of the customer bank details verification or update process.\n", "properties": { "status": { "type": "string", "description": "The current status of the customer bank information verification or update process.\n", "enum": [ "CORRECT", "INCORRECT", "UNCERTAIN" ], "example": "CORRECT" }, "detailed_error_message": { "type": "string", "description": "A detailed explanation of the error encountered during the processing of the customer bank information.\n", "example": "Bank account number is invalid" } } }, "refund": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Refund", "description": "A single refund associated with a payment.\n", "properties": { "id": { "type": "string", "pattern": "^\\d+$", "description": "Refund ID.\n", "example": "12345" }, "merchant_refund_code": { "type": "string", "nullable": true, "description": "Merchant's refund identifier.\n", "example": "merchant-refund-001" }, "status": { "type": "string", "description": "Refund status.\n", "example": "CO" }, "request_date": { "allOf": [ { "$ref": "#/components/schemas/not-nullable-datetime" } ], "description": "Date of the refund request.\n", "example": "2027-06-12 12:30:40" }, "pending_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "Date the refund was set to pending.\n", "example": "2027-06-12 14:00:00" }, "confirm_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "Date the refund was confirmed.\n", "example": "2027-06-13 10:00:00" }, "cancel_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "Date the refund was cancelled.\n", "example": null }, "amount_ext": { "type": "string", "description": "Refund amount in the original currency.\n", "example": "49.90" }, "description": { "type": "string", "nullable": true, "description": "Refund description.\n", "example": "Customer requested refund" }, "fill_bank_data_url": { "type": "string", "nullable": true, "description": "URL for the customer to fill in bank data for refund disbursement. Present only when applicable.\n", "example": "https://sandbox.ebanxpay.com/refund/fill-bank-data/abc123" }, "paid_date": { "allOf": [ { "$ref": "#/components/schemas/nullable-datetime" } ], "description": "Date the refund was paid out. Present only when the refund has been paid.\n", "example": "2027-06-14 09:00:00" }, "amount_local": { "type": "string", "nullable": true, "description": "Refund amount in local currency. Present only when the merchant has the `return_amount_local` config enabled.\n", "example": "49.90" }, "settlement": { "type": "object", "title": "Settlement", "nullable": true, "description": "Settlement information for the refund. Present only when the refund has been settled.\n", "properties": { "transfer_date": { "type": "string", "format": "date", "description": "Date of the settlement transfer.\n", "example": "2024-06-15" }, "amount": { "type": "number", "description": "Total settlement amount (cost + fee).\n", "example": 50 } } }, "refund_status_details": { "type": "object", "title": "Refund Status Details", "nullable": true, "description": "Details about the refund status reason.\n", "properties": { "cancellation_reason": { "type": "string", "nullable": true, "description": "The reason for the refund cancellation.\n", "example": "Merchant requested cancellation" }, "cancellation_reason_code": { "type": "string", "nullable": true, "description": "The code for the cancellation reason.\n", "example": "MERCHANT_REQUEST" }, "can_have_settlement": { "type": "boolean", "description": "Whether the refund can have a settlement.\n", "example": true }, "can_be_cancelled": { "type": "boolean", "description": "Whether the refund can be cancelled.\n", "example": false }, "pending_reason_code": { "type": "string", "description": "Code indicating the reason for the pending status.\n", "example": "WAITING_BANK_CONFIRMATION" }, "pending_reason_message": { "type": "string", "description": "Message explaining the pending reason.\n", "example": "Waiting for bank confirmation" }, "status_reason_code": { "type": "string", "description": "Code indicating the reason for the current status.\n", "example": "CONFIRMED" }, "status_reason_description": { "type": "string", "description": "Description explaining the refund status.\n", "example": "Refund has been confirmed by the acquirer" } } }, "authcode": { "type": "string", "description": "Authorization code returned by the acquirer for the refund transaction.\n", "example": "XYZ789" }, "rtrID": { "type": "string", "description": "PIX Return Transaction ID (end-to-end identifier for the PIX refund).\n", "example": "D12345678202406151000abcdef123456" }, "email_first_date": { "type": "string", "nullable": true, "description": "Date when the first refund notification email was sent.\n", "example": "2024-06-10 08:00:00" }, "email_last_date": { "type": "string", "nullable": true, "description": "Date when the most recent refund notification email was sent.\n", "example": "2024-06-12 10:30:00" }, "email_quantity": { "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^\\d+$" } ], "description": "Number of refund notification emails sent.\n", "example": 3 }, "bank_info_customer_filled": { "oneOf": [ { "type": "integer" }, { "type": "boolean" } ], "description": "Indicates whether the customer has filled in their bank information for the refund.\n", "example": 1 }, "bank_info_customer_filled_date": { "type": "string", "nullable": true, "description": "Date when the customer filled in their bank information.\n", "example": "2024-06-11 15:00:00" }, "customer_bank_info_status": { "$ref": "#/components/schemas/customer-bank-info-status" }, "single_transaction": { "type": "object", "title": "Single Transaction", "description": "Single transaction (crossborder split) amounts for this refund.\n", "properties": { "amount_local": { "type": "string", "description": "The local portion amount as a decimal string.\n", "example": "35.00" }, "amount_crossborder": { "type": "string", "description": "The crossborder portion amount as a decimal string.\n", "example": "14.90" } } } } }, "refund-transaction-reference": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Refund Transaction Reference", "description": "A transaction reference returned for a refund.\n", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The reference type. `arn` is an acquirer reference number and `tlid` is a\ntransaction link identifier.\n", "enum": [ "arn", "tlid" ], "example": "arn" }, "value": { "type": "string", "description": "The transaction reference value.", "example": "12345678901234567890123" } } }, "query-refund": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Query Refund", "description": "A single refund in the query response. Extends the shared refund object with\nfields that are returned exclusively by the query endpoint.\n", "allOf": [ { "$ref": "#/components/schemas/refund" }, { "type": "object", "title": "Query Refund Extra Fields", "properties": { "refund_method": { "type": "string", "description": "The method used to process the refund.\n", "enum": [ "bank-transfer", "card", "gateway" ], "example": "bank-transfer" }, "refund_letter": { "type": "string", "description": "URL to the refund letter document.\n", "example": "https://sandbox.ebanxpay.com/refund/letter/ref123" }, "transaction_references": { "type": "array", "description": "Transaction references associated with the refund.\n", "items": { "$ref": "#/components/schemas/refund-transaction-reference" } } } } ] }, "chargeback": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Query Chargeback", "description": "A JSON object that represents a chargeback linked to this payment.\n", "properties": { "chargeback_public_id": { "type": "string", "description": "The public identifier for the chargeback.\n", "example": "chb_abc123def456" }, "create_date": { "type": "string", "description": "The date and hour when the chargeback was imported into the system. UTC Date.\n", "example": "2024-03-15 10:30:00" }, "chargeback_date": { "type": "string", "description": "The date when the chargeback occurred.\n", "example": "2024-03-14" }, "description": { "type": "string", "description": "Description of the chargeback.\n", "example": "Unauthorized transaction" }, "reason_code": { "type": "string", "description": "A code that specifies the reason for the chargeback.\n", "example": "4837" }, "amount_ext": { "type": "string", "description": "Amount in the external currency.\n", "example": "100.00" }, "dispute_status": { "type": "string", "description": "The current status of the chargeback dispute.\n", "enum": [ "Processing", "Under Analysis", "Dispute Won", "Dispute Lost", "Evidence Required", "Not disputed" ], "example": "Processing" }, "settled": { "type": "boolean", "description": "Indicates whether the chargeback has been settled.\n", "example": false }, "settlement_date": { "type": "string", "nullable": true, "description": "The date and time when the chargeback was settled.\n", "example": "2024-04-01 14:00:00" }, "settlement_amount": { "type": "string", "nullable": true, "description": "The total value amount settled for the chargeback.\n", "example": "100.00" }, "settlement_currency": { "type": "string", "nullable": true, "description": "The currency in which the settlement was made.\n", "example": "USD" } } }, "transactor-info": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Transactor Info", "description": "Information about the transactor.\n", "properties": { "name": { "type": "string", "description": "Name of the transactor.\n", "example": "João Santos" }, "document": { "type": "string", "description": "Document identifier of the transactor.\n", "example": "123.456.789-00" }, "bank_details": { "type": "string", "description": "Details of the bank associated with the transactor.\n", "example": "Banco do Brasil - AG 1234 CC 56789-0" }, "bank_name": { "type": "string", "description": "Name of the bank associated with the transactor.\n", "example": "Banco do Brasil" }, "bank_branch": { "type": "string", "description": "Bank branch code.\n", "example": "1234" }, "bank_account": { "type": "string", "description": "Bank account number.\n", "example": "56789-0" }, "account_type": { "type": "string", "description": "Type of the bank account (e.g., checking, savings).\n", "example": "checking" } } }, "query-extra-fields": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Query Extra Fields", "description": "Fields exclusive to the query response that are not part of the shared payment response base\nor any payment-method-specific response schema. Also overrides `customer` and `refunds`\nwith their query-specific variants, which include fields returned only by the query endpoint.\n", "properties": { "customer": { "$ref": "#/components/schemas/query-customer" }, "refunds": { "type": "array", "nullable": true, "description": "List of refunds associated with the payment, including query-only fields.\n", "items": { "$ref": "#/components/schemas/query-refund" } }, "chargeback": { "$ref": "#/components/schemas/chargeback" }, "customer_bank_info_status": { "$ref": "#/components/schemas/customer-bank-info-status" }, "transactor_info": { "$ref": "#/components/schemas/transactor-info" } } }, "query-response": { "x-schema-group": "Responses", "title": "Query Response", "type": "object", "description": "JSON object with the payment data.\nThe response parameters will vary depending on the chosen payment method.\n", "properties": { "status": { "type": "string", "description": "The status of the request (SUCCESS or ERROR).\n", "example": "SUCCESS", "minLength": 5, "maxLength": 7 }, "payment": { "description": "A JSON object that represents the payment.\nReuses the same country/payment-method response union as the Direct endpoint,\nadding the fields that are exclusive to the Query response.\n", "allOf": [ { "$ref": "#/components/schemas/payment-response-27" }, { "$ref": "#/components/schemas/customization-extras" }, { "$ref": "#/components/schemas/query-extra-fields" } ] } } }, "query-error-code": { "title": "Query Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Query-specific error codes returned by the Query API endpoint.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-Q-1" ], "description": "Parameters hash or merchant_payment_code not informed." }, { "enum": [ "BP-Q-2" ], "description": "Payment not found for the merchant." } ], "example": "BP-Q-1" }, "query-error-response": { "x-schema-group": "Responses", "title": "Query Error Response", "description": "Error response returned when a query request fails (e.g. payment not found, invalid hash, or authentication error).\n", "type": "object", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/query-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code identifying what went wrong. Includes Query-specific and Authentication error codes.\n", "example": "BP-Q-1" }, "status_message": { "type": "string", "description": "A human-readable error message describing what went wrong.\n", "example": "Parameters hash or merchant_payment_code not informed" } } }, "cancel-request": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Cancel Request", "description": "The cancel operation is a server-to-server operation that cancels payments.\nYou can cancel a payment if, and only if, its status is open (OP) or pending (PE).\nConfirmed payments (CO) cannot be cancelled.\n\nThe payment to be cancelled is identified by either `hash` or `merchant_payment_code`\n(at least one of them is required).\n", "properties": { "hash": { "type": "string", "description": "The payment hash (EBANX unique identifier).\n", "x-conditional": "Required if merchant_payment_code is not provided", "minLength": 48, "maxLength": 48, "example": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9" }, "merchant_payment_code": { "type": "string", "description": "The payment hash Merchant Payment Code (unique merchant ID).\n", "x-conditional": "Required if hash is not provided", "minLength": 1, "maxLength": 40, "example": "1461416920319" }, "cancel_note": { "type": "string", "description": "An optional note describing the reason for the cancellation.\n", "example": "Customer requested cancellation" } }, "anyOf": [ { "required": [ "hash" ] }, { "required": [ "merchant_payment_code" ] } ] }, "cancel-response": { "x-schema-group": "Responses", "title": "Cancel Response", "type": "object", "description": "JSON object returned when a payment is successfully cancelled.\nThe payment object reuses the same country/payment-method response union as the Direct and\nQuery endpoints. Because a cancelled payment is in the `CA` status, payment-method-specific\nfields that only exist while a payment is pending are not present in this response.\n", "properties": { "status": { "type": "string", "description": "The status of the request (SUCCESS or ERROR).\n", "example": "SUCCESS", "minLength": 5, "maxLength": 7 }, "operation": { "type": "string", "description": "The operation performed. Always `cancel` for this endpoint.\n", "enum": [ "cancel" ], "example": "cancel" }, "payment": { "description": "A JSON object that represents the cancelled payment.\nReuses the same country/payment-method response union as the Direct endpoint.\n", "allOf": [ { "$ref": "#/components/schemas/payment-response-27" }, { "$ref": "#/components/schemas/customization-extras" }, { "type": "object", "title": "Cancel Response Extra Fields", "properties": { "customer": { "$ref": "#/components/schemas/customer" } } } ] } } }, "cancel-error-code": { "title": "Cancel Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Cancel-specific error codes returned by the Cancel API endpoint.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-CAN-1" ], "description": "Parameters hash or merchant_payment_code not informed." }, { "enum": [ "BP-CAN-2" ], "description": "Payment not found for the merchant." }, { "enum": [ "BP-CAN-3" ], "description": "Payment is already cancelled." }, { "enum": [ "BP-CAN-4" ], "description": "Payment cannot be cancelled because its status is not open (OP) or pending (PE)." }, { "enum": [ "BP-CAN-5" ], "description": "Payment cannot be cancelled (e.g. the payment method does not allow cancellation)." }, { "enum": [ "BP-CAN-6" ], "description": "Payment cannot be cancelled on the due date." }, { "enum": [ "BP-CAN-7" ], "description": "Gateway unavailable while cancelling payment." } ], "example": "BP-CAN-4" }, "cancel-error-response": { "x-schema-group": "Responses", "title": "Cancel Error Response", "description": "Error response returned when a cancel request fails (e.g. payment not found, payment cannot be\ncancelled in its current status, or an authentication error).\n", "type": "object", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/cancel-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code identifying what went wrong. Includes Cancel-specific and Authentication error codes.\n", "example": "BP-CAN-4" }, "status_message": { "type": "string", "description": "A human-readable error message describing what went wrong.\n", "example": "Payment cannot be cancelled, status is CO" } } }, "bank-transfer-info": { "type": "object", "title": "Brazil - Bank Transfer 🇧🇷", "required": [ "bank_name", "bank_branch", "bank_account", "account_type", "bank_account_holder_document", "bank_account_holder_name" ], "properties": { "bank_name": { "type": "string", "description": "Name of the banking institution. See the complete list below:\n\n**Available for Savings Accounts:**\n- 001 Banco do Brasil\n- 237 Bradesco\n- 341 Itaú\n- 104 Caixa Econômica\n- 033 Santander\n\n**Available for Checking Accounts:**\n- 104 Caixa Econômica\n- 001 Banco do Brasil\n- 341 Itaú\n- 237 Bradesco\n- 033 Santander\n- 212 Banco Original S.A.\n- 290 PagSeguro Internet S/A\n- 318 Banco BMG S.A.\n- 336 Banco C6 S.A.\n- 655 Neon / Banco Votorantim S.A.\n- 756 Bancoob\n- 021 Banestes\n- 077 Inter\n- 041 Banrisul\n- 748 Banco Cooperativo Sicredi S.A.\n- 745 Banco Citibank S.A.\n- 260 Nu Pagamentos S.A.\n- 422 Banco Safra S.A.\n- 082 Topazio S.A.\n- 003 Banco da Amazônia S.A.\n- 004 Banco do Nordeste\n- 010 Credicoamo Crédito Rural Cooperativa\n- 012 Banco Inbursa S.A.\n- 024 Bandepe S.A.\n- 025 Banco Alfa S.A.\n- 037 Banpara\n- 040 Banco Cargill S.A.\n- 047 Banese\n- 063 Banco Bradescard S.A.\n- 064 Goldman Sachs do Brasil Banco Múltiplo S. A.\n- 065 Banco AndBank (Brasil) S.A.\n- 066 Banco Morgan Stanley S. A.\n- 069 Banco Crefisa S.A.\n- 070 BRB - Banco de Brasília S.A.\n- 074 Banco J. Safra S.A.\n- 084 Unicred Norte do Paraná\n- 085 Cooperativa Central de Crédito Urbano (CECRED)\n- 089 Cooperativa de Crédito Rural da Região da Mogiana\n- 091 Unicred Central do Rio Grande do Sul\n- 093 Pólocred Sociedade de Crédito ao Microempreendedor e à Empresa de Pequeno Porte\n- 094 Banco Finaxis S.A.\n- 096 Banco B3 S.A.\n- 097 Credisis - Central de Cooperativas de Crédito Ltda.\n- 098 Credialiança Cooperativa de Crédito Rural\n- 099 Uniprime Central – Central Interestadual de Cooperativas de Crédito Ltda.\n- 107 Banco Bocom BBM S.A.\n- 108 PortoCred S.A. Crédito, Financiamento e Investimento\n- 120 Banco Rodobens SA\n- 121 Banco Agibank S.A.\n- 124 Banco Woori Bank do Brasil S.A.\n- 125 Plural S.A. Banco Múltiplo\n- 130 Caruana S.A. Sociedade de Crédito Financiamento e Investimento\n- 132 ICBC do Brasil Banco Múltiplo S.A.\n- 133 Cresol\n- 136 Confederação Nacional das Cooperativas Centrais Unicred Ltda – Unicred do Brasil\n- 139 Intesa Sanpaolo Brasil S.A. - Banco Múltiplo\n- 163 Commerzbank Brasil S.A. - Banco Múltiplo\n- 174 Pernambucanas Financiadora S.A. Crédito Financiamento e Investimento\n- 197 Stone Pagamentos S.A.\n- 208 Banco BTG Pactual S.A.\n- 218 Banco BS2 S.A.\n- 224 Banco Fibra S.A.\n- 233 Banco Cifra S.A.\n- 241 Banco Clássico S.A.\n- 243 Banco Máxima S.A.\n- 246 Banco ABC Brasil S.A.\n- 249 Banco Investcred Unibanco S.A.\n- 250 BCV - Banco de Crédito e Varejo S/A\n- 254 Parana Banco S. A.\n- 265 Banco Fator S.A.\n- 266 Banco Cédula S.A.\n- 279 Cooperativa de Crédito Rural de Primavera do Leste\n- 280 Avista S.A. Crédito Financiamento e Investimento\n- 281 Cooperativa de Crédito Rural Coopavel\n- 299 Sorocred - Crédito Financiamento e Investimento S/A\n- 301 BPP Instituição de Pagamento S.A.\n- 320 Banco Industrial e Comercial S.A. (BICBANCO)\n- 322 Cooperativa de Crédito Rural de Abelardo Luz - Sulcredi/Crediluz\n- 323 MercadoPago.com Representações Ltda.\n- 340 Super Pagamentos e Administração de Meios Eletrônicos S.A.\n- 366 Banco Société Générale Brasil S.A.\n- 370 Banco Mizuho do Brasil S.A.\n- 376 Banco J. P. Morgan S. A.\n- 389 Banco Mercantil do Brasil S.A.\n- 399 Kirton Bank S.A. - Banco Múltiplo\n- 477 Citibank N.A.\n- 487 Deutsche Bank S.A. - Banco Alemão\n- 488 JPMorgan Chase Bank National Associatio\n- 623 Banco Pan S.A.\n- 633 Banco Rendimento S.A\n- 634 Banco Triângulo S.A.\n- 637 Banco Sofisa S. A.\n- 654 Banco A.J. Renner S.A\n- 707 Banco Daycoval S.A.\n- 739 Banco Cetelem S.A.\n- 743 Banco Semear S.A.\n- 746 Banco Modal S.A.\n- 751 Scotiabank Brasil S.A. Banco Múltiplo\n- 753 Novo Banco Continental S.A. - Banco Múltiplo\n- 754 Banco Sistema S.A.\n", "example": "104 Caixa Econômica" }, "bank_branch": { "type": "string", "description": "Bank branch. The branch can have a digit. If have so, the digit should be separated with a hyphen\n", "maxLength": 7, "example": "00001-2" }, "bank_account": { "type": "string", "description": "Account number, if have digit should be separated with a hyphen\n", "maxLength": 15, "example": "08251777-6" }, "account_type": { "type": "string", "description": "Account type\nC - for checking account\nS - for savings account\n", "maxLength": 1, "example": "C" }, "bank_details": { "type": "string", "description": "Only necessary when the bank is 104 Caixa Econômica\nValid values are: \"001\", \"002\", \"003\", \"006\", \"007\", \"013\", \"022\", \"023\", \"028\", \"043\", \"131\", \"1288\"\n", "maxLength": 4, "example": 1 }, "bank_account_holder_document": { "type": "string", "description": "Bank account holder document: CPF or CNPJ\n", "maxLength": 14, "example": 85351346893 }, "bank_account_holder_name": { "type": "string", "description": "Bank account holder name\n", "maxLength": 100, "example": "José Silva" } } }, "pix-info": { "type": "object", "title": "Brazil - Pix 🇧🇷", "required": [ "bank_account_holder_document", "bank_account_holder_name", "pix_key" ], "properties": { "bank_account_holder_name": { "type": "string", "description": "Bank account holder name\n", "maxLength": 100, "example": "José Silva" }, "bank_account_holder_document": { "type": "string", "description": "Bank account holder document: CPF or CNPJ\n", "maxLength": 14, "example": 85351346893 }, "pix_key": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "Pix key information - This field accepts one of:\n- EMAIL: Email address for Pix transactions. Example: \"josesilva@email.com\"\n- CPF: CPF number for Pix transactions. Example: \"123.456.789-01\"\n- CNPJ: CNPJ number for Pix transactions. Example: \"12.345.678/0001-90\"\n- PHONE: Phone number for Pix transactions. Example: \"+554191457164\"\n- RANDOM: Random Pix key for transactions. Example: \"5b5432e5-aa6d-40b0-9ff7-0226f5a0186f\"\n", "maxLength": 36 } } }, "bank-info": { "type": "object", "title": "Chile 🇨🇱", "required": [ "bank_name", "bank_account", "bank_account_holder_document", "bank_account_holder_name" ], "properties": { "bank_name": { "type": "string", "description": "Name of the banking institution. See the complete list below:\n\n- 001 BANCO DE CHILE\n- 001 BANCO EDWARDS | CITI\n- 001 BANCO ATLAS S.A.\n- 001 BANCO CREDICHILE\n- 009 BANCO INTERNACIONAL\n- 012 BANCO DEL ESTADO DE CHILE\n- 014 SCOTIABANK CHILE\n- 016 BANCO DE CREDITO E INVERSIONES\n- 017 BANCO DO BRASIL S.A\n- 028 BANCO BICE\n- 031 HSBC BANK (CHILE)\n- 037 BANCO SANTANDER-CHILE\n- 039 ITAÚ CORPBANCA\n- 041 JP MORGAN CHASE BANK N. A.\n- 043 BANCO DE LA NACION ARGENTINA\n- 045 MUFG Bank Ltd.\n- 049 BANCO SECURITY\n- 051 BANCO FALABELLA\n- 053 BANCO RIPLEY\n- 055 BANCO CONSORCIO\n- 059 BANCO BTG PACTUAL CHILE\n- 060 CHINA CONSTRUCTION BANK AGENCIA EN CHILE\n- 061 BANK OF CHINA AGENCIA EN CHILE\n- 504 SCOTIABANK AZUL (BBVA)\n- 730 Tenpo\n", "example": "001 BANCO DE CHILE" }, "bank_account": { "type": "string", "description": "Account number, only numbers allowed.\n", "example": 82517776 }, "bank_account_holder_document": { "type": "string", "description": "Bank account holder document\n", "example": "15798599-K" }, "bank_account_holder_name": { "type": "string", "description": "Bank account holder name\n", "maxLength": 100, "example": "José Silva" } } }, "bank-info-2": { "type": "object", "title": "Colombia 🇨🇴", "required": [ "bank_name", "bank_account", "bank_account_holder_document", "bank_account_holder_name" ], "properties": { "bank_name": { "type": "string", "description": "Name of the banking institution. See the complete list below:\n\n- 1040 Banco Agrario\n- 1052 Banco AV Villas\n- 1032 Banco Caja Social BCSC SA\n- 1019 Banco Colpatria\n- 1066 Banco Cooperativo Coopcentral\n- 1006 Banco Corpbanca Colombia S.A\n- 1051 Banco Davivienda SA\n- 1001 Banco de Bogotá\n- 1023 Banco de Occidente\n- 1062 Banco Falabella S.A\n- 1063 Banco Finandina S.A\n- 1012 Banco GNB Sudameris\n- 1064 Banco Multibank S.A\n- 1060 Banco Pichincha\n- 1002 Banco Popular\n- 1058 Banco Procredit Colombia\n- 1065 Banco Santander de Negocios Colombia S.A.\n- 1007 Bancolombia\n- 1061 Bancoomeva\n- 1013 BBVA Colombia\n- 1009 Citibank\n- 1370 Coltefinanciera S.A\n- 1292 Confiar Cooperativa Financiera\n- 1283 Cooperativa Financiera de Antioquia\n- 1289 Cootrafa Cooperativa Financiera\n- 1121 Financiera Juriscoop Compañía de Financiamiento\n- 1014 Helm Bank S.A\n- 1059 Bancamia S.A.\n- 1558 Banco Credifinanciera S.A.\n- 1071 Banco J.P. Morgan Colombia S.A.\n- 1047 Banco Mundo Mujer\n- 1069 Banco Serfinanza S.A.\n- 1053 Banco W S.A.\n- 1031 Bancoldex S.A.\n- 1291 Coofinep Cooperativa Financier\n- 1551 Daviplata\n- 1303 Giros y Finanzas CF\n- 1637 Iris\n- 1070 Lulo Bank S.A.\n- 1067 Mibanco S.A.\n- 1801 Movii\n- 1507 Nequi\n- 1151 Rappipay\n", "example": "1032 Banco Caja Social BCSC SA" }, "bank_account": { "type": "string", "description": "Account number, only numbers allowed.\n", "example": 123456 }, "bank_account_holder_document": { "type": "string", "description": "Bank account holder document, only numbers allowed.\n", "example": 123456789 }, "bank_account_holder_name": { "type": "string", "description": "Bank account holder name\n", "maxLength": 100, "example": "José Silva" } } }, "bank-info-3": { "type": "object", "title": "Mexico 🇲🇽", "required": [ "clabe", "bank_account_holder_name" ], "properties": { "clabe": { "type": "string", "description": "Clabe. The first 3 digits must represent a valid bank code. See the complete list below:\n\n- 001 => BANCO - BANXICO\n- 002 => BANAM - BANAMEX\n- 006 => BCEXT - BANCOMEXT\n- 009 => BOBRA - BANOBRAS\n- 012 => BACOM - BBVA BANCOMER\n- 014 => BANME - BANCO SANTANDER\n- 019 => BEJER - BANJERCITO\n- 021 => BITAL - HSBC\n- 030 => BAJIO - BAJIO\n- 032 => BAIXE - IXE\n- 036 => BINBU - INBURSA\n- 037 => BINTE - INTERACCIONES\n- 042 => MIFEL - MIFEL\n- 044 => COMER - SCOTIA BANK INVERLAT\n- 058 => BANRE - BANREGIO\n- 059 => BINVE - INVEX\n- 060 => BANSI - BANSI\n- 062 => BAFIR - AFIRME\n- 072 => BBANO - BANORTE / IXE\n- 102 => ABNBA - ROYAL BANK OF SCOTLAND\n- 103 => AMEX - AMERICAN EXPRESS\n- 106 => BAMSA - BANK OF AMERICA\n- 108 => TOKYO - TOKYO\n- 110 => CHASE - JP MORGAN\n- 112 => CMCA - BANCO MONEX\n- 113 => DRESD - VE POR MAS\n- 116 => INGBA - ING\n- 124 => DEUTB - DEUTSCHE\n- 126 => CRESU - CREDIT SUISSE\n- 127 => BAZTE - AZTECA\n- 128 => BAUTO - BANCO AUTOFIN\n- 129 => BARCL - BARCLAYS BANK\n- 130 => BCOMP - BANCO COMPARTAMOS\n- 131 => FAMSA - BANCO DE AHORRO FAMSA\n- 132 => MULTI - BANCO MULTIVA\n- 133 => PRUDE - ACTINVER BANK\n- 134 => BWALL - BANCO WAL MART\n- 135 => NAFIN - NACIONAL FINANCIERA\n- 136 => REGIO - BANCO REGIONAL SA\n- 137 => COPEL - BANCOPPEL\n- 138 => AMIGO - BANCO AMIGO\n- 139 => UBSBA - UBS BANK MEXICO\n- 140 => FACIL - BANCO FACIL\n- 141 => VOLKS - VOLKSWAGEN BANK\n- 143 => CONSU - BANCO CONSULTORIA\n- 145 => BBASE - BANCO BASE\n- 147 => AGROF - BANKAOOL\n- 166 => BANSE - BANSEFI\n- 168 => HIFED - HIPOTECARIA FEDERAL\n- 646 => 90646 - STP\n", "maxLength": 18, "example": 14027000000000008 }, "bank_account_holder_name": { "type": "string", "description": "Bank account holder name\n", "maxLength": 100, "example": "José Silva" } } }, "refund-request": { "type": "object", "title": "ws/refund", "description": "This is a server-to-server operation that handles payment refunds.\nThere are two sub-operations: request and cancel.\nThe request operation requests a refund. The cancel operation cancels a refund.\n", "required": [ "operation", "hash" ], "properties": { "operation": { "type": "string", "description": "The available operations are:\nrequest: request a new refund.\ncancel: cancel a refund.\n", "minLength": 6, "maxLength": 7, "example": "request" }, "hash": { "type": "string", "description": "The payment hash (EBANX unique identifier).\n", "minLength": 48, "maxLength": 48, "example": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221" }, "amount": { "type": "number", "description": "The amount to be refunded; expressed in the original payment currency.\n**Required for request.**\n", "example": 100 }, "description": { "type": "string", "description": "Description of the refund reason.\n**Required for request.**\n", "minLength": 1, "maxLength": 500, "example": "Order did not arrive" }, "merchant_refund_code": { "type": "string", "description": "The ID of the refund on the merchant system. Unique\n**Required for request**\n", "minLength": 1, "maxLength": 40, "example": 787653 }, "refund_id": { "type": "integer", "description": "The ID of the refund to be cancelled.\n**Required for cancel.**\n", "minLength": 20, "maxLength": 20, "example": 3784756 }, "bank_info": { "type": "object", "title": "Bank Info", "description": "Object that holds bank information for the refund. **Although this object is not mandatory, if you choose to use it, all it's elements are required to be provided**\n", "oneOf": [ { "$ref": "#/components/schemas/bank-transfer-info" }, { "$ref": "#/components/schemas/pix-info" }, { "$ref": "#/components/schemas/bank-info" }, { "$ref": "#/components/schemas/bank-info-2" }, { "$ref": "#/components/schemas/bank-info-3" } ] } } }, "refund-response": { "title": "Refund Response", "type": "object", "description": "JSON object with the payment data. \nThe response parameters will vary depending on the chosen payment method.\n", "properties": { "status": { "type": "string", "example": "SUCCESS", "description": "The status of the the request (SUCCESS or ERROR).\n", "minLength": 5, "maxLength": 7 }, "payment": { "type": "object", "title": "Payment", "description": "A JSON object that represents the payment.\n", "properties": { "hash": { "type": "string", "example": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221", "minLength": 48, "maxLength": 48, "description": "The payment hash (EBANX unique identifier).\n" }, "country": { "type": "string", "example": "br", "minLength": 2, "maxLength": 2, "description": "The country of the payment.\n" }, "merchant_payment_code": { "type": "string", "example": "merchant-payment-code-123", "minLength": 1, "maxLength": 40, "description": "The payment hash Merchant Payment Code (unique merchant ID).\n" }, "order_number": { "type": "string", "example": "ORD-12345", "minLength": 1, "maxLength": 40, "description": "The order number, optional identifier set by the merchant. \nYou can have multiple payments with the same order number.\n" }, "status": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "The payment status. The following statuses are available:\n\n- **OP**: the customer has not yet filled the payment details on the EBANX Checkout. It can change either to CA (time out) or PE.\n- **PE**: the payment is pending confirmation. It can change either to CA or CO.\n- **CO**: the payment is confirmed (paid).\n- **CA**: the payment is cancelled.\n" }, "status_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of the last status change.\n" }, "open_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was created.\n" }, "confirm_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was confirmed.\n" }, "transfer_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was settled.\n" }, "amount_br": { "type": "number", "example": 100, "description": "The amount in local currency.\n" }, "amount_iof": { "type": "number", "example": 100, "description": "The tax amount in local currency (varies between countries).\n" }, "amount_ext": { "type": "number", "example": 100, "description": "The amount in the original currency.\n" }, "currency_rate": { "type": "number", "example": 2.35, "description": "The exchange rate used in the payment.\n" }, "currency_ext": { "type": "string", "example": "BRL", "minLength": 3, "maxLength": 3, "description": "ISO 4217 three letter code of the original currency.\n" }, "due_date": { "type": "string", "example": "2024-01-15", "minLength": 10, "maxLength": 10, "description": "Expiry date of the payment (not applicable to all payment methods).\nFormat: dd/mm/yyyy\n" }, "instalments": { "type": "integer", "example": 1, "description": "Number of instalments for the payment, default value is 1.\n" }, "payment_type_code": { "type": "string", "example": "amex", "minLength": 1, "maxLength": 32, "description": "The code of the payment method. The supported codes are:\n\n- **amex**: American Express credit card (Brazil, Mexico, Colombia).\n- **bancodobrasil**: Banco do Brasil bank transfer (Brazil).\n- **banrisul**: Banrisul bank transfer (Brazil).\n- **banktransfer**: Bank transfer (Brazil).\n- **boleto**: Boleto bancário (Brazil).\n- **bradesco**: Bradesco bank transfer (Brazil).\n- **carnet**: CARNET credit card (Mexico).\n- **diners**: Diners credit card (Brazil, Colombia).\n- **discover**: Discover credit card (Brazil).\n- **ebanxaccount**: EBANX Account (Brazil).\n- **eft**: Bank Transfer (Colombia).\n- **elo**: Elo credit card (Brazil).\n- **hipercard**: Hipercard credit card (Brazil).\n- **itau**: Itaú bank transfer (Brazil).\n- **mastercard**: MasterCard credit card (Brazil, Mexico, Colombia).\n- **multicaja**: Multicaja (Chile).\n- **oxxo**: OXXO (Mexico).\n- **pagoefectivo**: PagoEfectivo (Peru).\n- **pagosnet**: PagosNet (Bolivia).\n- **paynet**: Paynet (Mexico).\n- **safetypay**: SafetyPay (Peru, Ecuador, Checkout only).\n- **safetypay-cash**: SafetyPay Cash (Peru, Ecuador).\n- **safetypay-online**: SafetyPay Online (Peru, Ecuador).\n- **sencillito**: Sencillito (Chile).\n- **servipag**: Servipag (Chile).\n- **spei**: SPEI bank transfer method (Mexico).\n- **visa**: Visa credit card (Brazil, Mexico, Colombia).\n- **webpay**: Webpay (Chile).\n", "enum": [ "amex", "carnet", "credimas", "diners", "discover", "elo", "hipercard", "mastercard", "naranja", "visa", "bancodobrasil", "banktransfer", "banrisul", "boleto", "bradesco", "cupon", "ebanxaccount", "eft", "itau", "multicaja", "oxxo", "pagoefectivo", "pagofacil", "pagosnet", "rapipago", "safetypay", "safetypay-cash", "safetypay-online", "sencillito", "servipag", "spei", "webpay" ] }, "details": { "type": "object", "title": "Details", "description": "A JSON object that represents the payment details.\n", "properties": { "billing_descriptor": { "type": "string", "example": "EBANX*DEMOMERCHANT", "description": "The billing descriptor of the payment.\n" } } }, "transaction_status": { "type": "object", "title": "Transaction Status", "description": "A JSON object that represents the payment credit card transaction.\n", "properties": { "acquirer": { "type": "string", "example": "EBANX", "minLength": 1, "description": "The acquirer that processed the transaction.\n" }, "code": { "type": "string", "example": "OK", "minLength": 2, "maxLength": 7, "description": "The transaction status code:\n\n**OK:** The transaction amount was approved.\n**NOK:** The acquirer did not approved the transaction. The customer must contact the issuer to check for any issue with his credit card.\n**RETRY:** Something went wrong with the process. You can retry with the same data. We recommend you to try more 3 times on different periods of time (first try, then second try after 2 hours after the first, etc).\n" }, "description": { "type": "string", "example": "The transaction was processed successfully", "minLength": 1, "maxLength": 500, "description": "The description for the status code, which is returned from the acquirer.\n" }, "authcode": { "type": "string", "example": "134903", "minLength": 1, "description": "Transaction authentication code in the acquirer.\n" } } }, "pre_approved": { "type": "boolean", "example": true, "description": "Flag that shows if a payment is pre-approved by the credit card acquirer.\n" }, "capture_available": { "type": "boolean", "example": true, "description": "Flag that shows if a payment is ready to be captured. Applies only to credit cards when auto_capture is set to false. Some remarks on this attribute:\n\nA payment can only be captured if pre_approved value is true, which means that the payment has been pre approved by the credit card acquirer. Before capture, an authorized payment has status as PE (pending). After the capture, the status changes to CO (confirmed). A payment can only be captured if the status is PE (pending). *Payments must be captured in 4 (four) days, otherwise they are automatically cancelled.\nNOTE: It can be changed up to 5 (five) days.\n" }, "redirect_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/redirect/payment", "description": "The URL the customer should be redirected to. Applies to certain payment methods using the Direct API.\n" }, "pay_with_balance_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/pay/balance/a1b2c3", "description": "If the customer has an EBANX Account profile and it has balance enough to pay for the created boleto, the response will contain this parameter responsible for redirecting the customer to his EBANX Account page so he can pay the boleto with his available balance.\n" }, "boleto_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/print/?hash=abc123", "description": "The boleto URL.\n" }, "boleto_barcode": { "type": "string", "example": "12345678901234567890123456789012345678901234567", "minLength": 47, "maxLength": 47, "description": "The boleto barcode number. (Boleto)\n" }, "cip_url": { "type": "string", "example": "https://customer.ebanx.com/cip", "description": "The CIP URL. (PagoEfectivo)\n" }, "cip_code": { "type": "string", "example": "123456781234", "minLength": 12, "maxLength": 12, "description": "The CIP code. (PagoEfectivo)\n" }, "refunds": { "type": "array", "description": "An array of objects that represent a refund linked to this payment. \nThis node will only be present if a refund was issued.\n", "items": { "type": "object", "title": "Refunds Item", "properties": { "id": { "type": "integer", "example": 100, "description": "The ID of the refund on EBANX.\n" }, "merchant_refund_code": { "type": "string", "example": "787653", "minLength": 1, "maxLength": 20, "description": "The ID of the refund on the merchant system (optional).\n" }, "status": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "The status of the refund:\n\n**RE (Requested):** The refund has been requested and is waiting to be processed. It can be cancelled while it has this status.\n**PE (Pending):** The refund is being processed. It cannot be cancelled anymore.\n**CO (Confirmed):** The refund was processed and the money was sent back to the customer.\n**CA (Cancelled):** The refund was cancelled.\n" }, "request_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the refund was created. UTC Date.\n" }, "pending_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the customer data was received. UTC Date.\n" }, "confirm_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the money was transferred to the customer. UTC Date.\n" }, "amount_ext": { "type": "number", "example": 100, "description": "The refunded amount in the original currency.\n" }, "description": { "type": "string", "example": "Customer requested a refund", "minLength": 1, "maxLength": 1500, "description": "Description of the refund reason.\n" } } } }, "chargeback": { "type": "object", "title": "Chargeback", "description": "A JSON object that represents a chargeback linked to this payment. \nThis node will only be present if a chargeback was issued.\n", "properties": { "create_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the chargeback was imported into the system. UTC Date.\n" }, "chargeback_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the chargeback was created by the acquirer on behalf of the customer. UTC Date.\n" }, "description": { "type": "string", "example": "Chargeback opened by the issuing bank", "minLength": 1, "maxLength": 1500, "description": "Description of the chargeback.\n" } } }, "chargeback_credit": { "type": "boolean", "example": true, "description": "Flag that shows if a chargeback credit was issued.\n" }, "clabe_account": { "type": "string", "example": "646180204800000001", "description": "(Only for SPEI payments) The customer’s CLABE account.\n" }, "clabe_reference": { "type": "string", "example": "1234567", "description": "(Only for SPEI payments) The reference for the current payment.\n" } } } } }, "refund-or-cancel-request": { "type": "object", "title": "ws/refundOrCancel", "description": "The refund or cancel operation is a server-to-server operation to cancel payments or create payments refunds.\nWhen the refundOrCancel operation is requested, the following will occur according to the payment status:\n- Open (OP) or Pending (PE) – the payment will be cancelled (status changes to CA), and no refund will be made.\n- Confirmed (CO) – it will be made a full refund of the payment to the customer.\n", "required": [ "hash" ], "properties": { "hash": { "type": "string", "description": "The payment hash (EBANX unique identifier).\nRequired if merchant_payment_code not provided.\n", "minLength": 48, "maxLength": 48, "example": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221" }, "description": { "type": "string", "description": "Description of the refund reason.\n**Required for request.**\n", "minLength": 1, "maxLength": 1500, "example": "Order did not arrive" }, "merchant_refund_code": { "type": "string", "description": "The ID of the refund on the merchant system.\n", "minLength": 1, "maxLength": 20, "example": 787653 } } }, "refund-or-cancel-response": { "title": "Refund Or Cancel Response", "type": "object", "description": "JSON object with the payment data. \nThe response parameters will vary depending on the chosen payment method.\n", "properties": { "status": { "type": "string", "example": "SUCCESS", "description": "The status of the the request (SUCCESS or ERROR).\n", "minLength": 5, "maxLength": 7 }, "payment": { "type": "object", "title": "Payment", "description": "A JSON object that represents the payment.\n", "properties": { "hash": { "type": "string", "example": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221", "minLength": 48, "maxLength": 48, "description": "The payment hash (EBANX unique identifier).\n" }, "country": { "type": "string", "example": "br", "minLength": 2, "maxLength": 2, "description": "The country of the payment.\n" }, "merchant_payment_code": { "type": "string", "example": "merchant-payment-code-123", "minLength": 1, "maxLength": 40, "description": "The payment hash Merchant Payment Code (unique merchant ID).\n" }, "order_number": { "type": "string", "example": "ORD-12345", "minLength": 1, "maxLength": 40, "description": "The order number, optional identifier set by the merchant. \nYou can have multiple payments with the same order number.\n" }, "status": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "The payment status. The following statuses are available:\n\n- **OP**: the customer has not yet filled the payment details on the EBANX Checkout. It can change either to CA (time out) or PE.\n- **PE**: the payment is pending confirmation. It can change either to CA or CO.\n- **CO**: the payment is confirmed (paid).\n- **CA**: the payment is cancelled.\n" }, "status_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of the last status change.\n" }, "open_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was created.\n" }, "confirm_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was confirmed.\n" }, "transfer_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was settled.\n" }, "amount_br": { "type": "number", "example": 100, "description": "The amount in local currency.\n" }, "amount_iof": { "type": "number", "example": 100, "description": "The tax amount in local currency (varies between countries).\n" }, "amount_ext": { "type": "number", "example": 100, "description": "The amount in the original currency.\n" }, "currency_rate": { "type": "number", "example": 2.35, "description": "The exchange rate used in the payment.\n" }, "currency_ext": { "type": "string", "example": "BRL", "minLength": 3, "maxLength": 3, "description": "ISO 4217 three letter code of the original currency.\n" }, "due_date": { "type": "string", "example": "2024-01-15", "minLength": 10, "maxLength": 10, "description": "Expiry date of the payment (not applicable to all payment methods).\nFormat: dd/mm/yyyy\n" }, "instalments": { "type": "integer", "example": 1, "description": "Number of instalments for the payment, default value is 1.\n" }, "payment_type_code": { "type": "string", "example": "amex", "minLength": 1, "maxLength": 32, "description": "The code of the payment method. The supported codes are:\n\n- **amex**: American Express credit card (Brazil, Mexico, Colombia).\n- **bancodobrasil**: Banco do Brasil bank transfer (Brazil).\n- **banrisul**: Banrisul bank transfer (Brazil).\n- **banktransfer**: Bank transfer (Brazil).\n- **boleto**: Boleto bancário (Brazil).\n- **bradesco**: Bradesco bank transfer (Brazil).\n- **carnet**: CARNET credit card (Mexico).\n- **diners**: Diners credit card (Brazil, Colombia).\n- **discover**: Discover credit card (Brazil).\n- **ebanxaccount**: EBANX Account (Brazil).\n- **eft**: Bank Transfer (Colombia).\n- **elo**: Elo credit card (Brazil).\n- **hipercard**: Hipercard credit card (Brazil).\n- **itau**: Itaú bank transfer (Brazil).\n- **mastercard**: MasterCard credit card (Brazil, Mexico, Colombia).\n- **multicaja**: Multicaja (Chile).\n- **oxxo**: OXXO (Mexico).\n- **pagoefectivo**: PagoEfectivo (Peru).\n- **pagosnet**: PagosNet (Bolivia).\n- **paynet**: Paynet (Mexico).\n- **safetypay**: SafetyPay (Peru, Ecuador, Checkout only).\n- **safetypay-cash**: SafetyPay Cash (Peru, Ecuador).\n- **safetypay-online**: SafetyPay Online (Peru, Ecuador).\n- **sencillito**: Sencillito (Chile).\n- **servipag**: Servipag (Chile).\n- **spei**: SPEI bank transfer method (Mexico).\n- **visa**: Visa credit card (Brazil, Mexico, Colombia).\n- **webpay**: Webpay (Chile).\n", "enum": [ "amex", "carnet", "credimas", "diners", "discover", "elo", "hipercard", "mastercard", "naranja", "visa", "bancodobrasil", "banktransfer", "banrisul", "boleto", "bradesco", "cupon", "ebanxaccount", "eft", "itau", "multicaja", "oxxo", "pagoefectivo", "pagofacil", "pagosnet", "rapipago", "safetypay", "safetypay-cash", "safetypay-online", "sencillito", "servipag", "spei", "webpay" ] }, "details": { "type": "object", "title": "Details", "description": "A JSON object that represents the payment details.\n", "properties": { "billing_descriptor": { "type": "string", "example": "EBANX*DEMOMERCHANT", "description": "The billing descriptor of the payment.\n" } } }, "transaction_status": { "type": "object", "title": "Transaction Status", "description": "A JSON object that represents the payment credit card transaction.\n", "properties": { "acquirer": { "type": "string", "example": "EBANX", "minLength": 1, "description": "The acquirer that processed the transaction.\n" }, "code": { "type": "string", "example": "OK", "minLength": 2, "maxLength": 7, "description": "The transaction status code:\n\n**OK:** The transaction amount was approved.\n**NOK:** The acquirer did not approved the transaction. The customer must contact the issuer to check for any issue with his credit card.\n**RETRY:** Something went wrong with the process. You can retry with the same data. We recommend you to try more 3 times on different periods of time (first try, then second try after 2 hours after the first, etc).\n" }, "description": { "type": "string", "example": "The transaction was processed successfully", "minLength": 1, "maxLength": 500, "description": "The description for the status code, which is returned from the acquirer.\n" }, "authcode": { "type": "string", "example": "134903", "minLength": 1, "description": "Transaction authentication code in the acquirer.\n" } } }, "pre_approved": { "type": "boolean", "example": true, "description": "Flag that shows if a payment is pre-approved by the credit card acquirer.\n" }, "capture_available": { "type": "boolean", "example": true, "description": "Flag that shows if a payment is ready to be captured. Applies only to credit cards when auto_capture is set to false. Some remarks on this attribute:\n\nA payment can only be captured if pre_approved value is true, which means that the payment has been pre approved by the credit card acquirer. Before capture, an authorized payment has status as PE (pending). After the capture, the status changes to CO (confirmed). A payment can only be captured if the status is PE (pending). *Payments must be captured in 4 (four) days, otherwise they are automatically cancelled.\nNOTE: It can be changed up to 5 (five) days.\n" }, "redirect_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/redirect/payment", "description": "The URL the customer should be redirected to. Applies to certain payment methods using the Direct API.\n" }, "pay_with_balance_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/pay/balance/a1b2c3", "description": "If the customer has an EBANX Account profile and it has balance enough to pay for the created boleto, the response will contain this parameter responsible for redirecting the customer to his EBANX Account page so he can pay the boleto with his available balance.\n" }, "boleto_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/print/?hash=abc123", "description": "The boleto URL.\n" }, "boleto_barcode": { "type": "string", "example": "12345678901234567890123456789012345678901234567", "minLength": 47, "maxLength": 47, "description": "The boleto barcode number. (Boleto)\n" }, "cip_url": { "type": "string", "example": "https://customer.ebanx.com/cip", "description": "The CIP URL. (PagoEfectivo)\n" }, "cip_code": { "type": "string", "example": "123456781234", "minLength": 12, "maxLength": 12, "description": "The CIP code. (PagoEfectivo)\n" }, "refunds": { "type": "array", "description": "An array of objects that represent a refund linked to this payment. \nThis node will only be present if a refund was issued.\n", "items": { "type": "object", "title": "Refunds Item", "properties": { "id": { "type": "integer", "example": 100, "description": "The ID of the refund on EBANX.\n" }, "merchant_refund_code": { "type": "string", "example": "787653", "minLength": 1, "maxLength": 20, "description": "The ID of the refund on the merchant system (optional).\n" }, "status": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "The status of the refund:\n\n**RE (Requested):** The refund has been requested and is waiting to be processed. It can be cancelled while it has this status.\n**PE (Pending):** The refund is being processed. It cannot be cancelled anymore.\n**CO (Confirmed):** The refund was processed and the money was sent back to the customer.\n**CA (Cancelled):** The refund was cancelled.\n" }, "request_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the refund was created. UTC Date.\n" }, "pending_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the customer data was received. UTC Date.\n" }, "confirm_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the money was transferred to the customer. UTC Date.\n" }, "amount_ext": { "type": "number", "example": 100, "description": "The refunded amount in the original currency.\n" }, "description": { "type": "string", "example": "Customer requested a refund", "minLength": 1, "maxLength": 1500, "description": "Description of the refund reason.\n" } } } }, "chargeback": { "type": "object", "title": "Chargeback", "description": "A JSON object that represents a chargeback linked to this payment. \nThis node will only be present if a chargeback was issued.\n", "properties": { "create_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the chargeback was imported into the system. UTC Date.\n" }, "chargeback_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the chargeback was created by the acquirer on behalf of the customer. UTC Date.\n" }, "description": { "type": "string", "example": "Chargeback opened by the issuing bank", "minLength": 1, "maxLength": 1500, "description": "Description of the chargeback.\n" } } }, "chargeback_credit": { "type": "boolean", "example": true, "description": "Flag that shows if a chargeback credit was issued.\n" }, "clabe_account": { "type": "string", "example": "646180204800000001", "description": "(Only for SPEI payments) The customer’s CLABE account.\n" }, "clabe_reference": { "type": "string", "example": "1234567", "description": "(Only for SPEI payments) The reference for the current payment.\n" } } } } }, "resend-bank-info-request": { "type": "object", "title": "ws/refund", "description": "The resend refund bank info is a server-to-server operation to update the bank info data in an existing refund.\n", "required": [ "hash", "bank_info", "merchant_refund_code", "refund_id" ], "properties": { "hash": { "type": "string", "description": "The payment hash (EBANX unique identifier).\n", "minLength": 48, "maxLength": 48, "example": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221" }, "merchant_refund_code": { "type": "string", "description": "The ID of the refund on the merchant system. Unique\n**Required for request**\n", "minLength": 1, "maxLength": 40, "example": 787653 }, "refund_id": { "type": "integer", "description": "The ID of the refund to be updated.\n**Required for resending.**\n", "minLength": 20, "maxLength": 20, "example": 3784756 }, "bank_info": { "type": "object", "title": "Bank Info", "description": "Object that holds bank information for the refund. **Although this object is not mandatory, if you choose to use it, all its elements are required to be provided**\n", "oneOf": [ { "$ref": "#/components/schemas/bank-transfer-info" }, { "$ref": "#/components/schemas/pix-info" }, { "$ref": "#/components/schemas/bank-info" }, { "$ref": "#/components/schemas/bank-info-2" }, { "$ref": "#/components/schemas/bank-info-3" } ] } } }, "resend-bank-info-response": { "title": "Resend Bank Info Response", "type": "object", "description": "JSON object with the payment data.\nThe response parameters will vary depending on the chosen payment method.\n", "properties": { "status": { "type": "string", "example": "SUCCESS", "description": "The status of the the request (SUCCESS or ERROR).\n", "minLength": 5, "maxLength": 7 }, "operation": { "type": "string", "example": "request", "description": "The operation performed by the endpoint.\n" }, "payment": { "type": "object", "title": "Payment", "description": "A JSON object that represents the payment.\n", "properties": { "hash": { "type": "string", "example": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221", "minLength": 48, "maxLength": 48, "description": "The payment hash (EBANX unique identifier).\n" }, "country": { "type": "string", "example": "br", "minLength": 2, "maxLength": 2, "description": "The country of the payment.\n" }, "merchant_payment_code": { "type": "string", "example": "merchant-payment-code-123", "minLength": 1, "maxLength": 40, "description": "The payment hash Merchant Payment Code (unique merchant ID).\n" }, "order_number": { "type": "string", "example": "ORD-12345", "minLength": 1, "maxLength": 40, "description": "The order number, optional identifier set by the merchant.\nYou can have multiple payments with the same order number.\n" }, "status": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "The payment status. The following statuses are available:\n\n- **OP**: the customer has not yet filled the payment details on the EBANX Checkout. It can change either to CA (time out) or PE.\n- **PE**: the payment is pending confirmation. It can change either to CA or CO.\n- **CO**: the payment is confirmed (paid).\n- **CA**: the payment is cancelled.\n" }, "status_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of the last status change.\n" }, "open_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was created.\n" }, "confirm_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was confirmed.\n" }, "transfer_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was settled.\n" }, "amount_br": { "type": "number", "example": 100, "description": "The amount in local currency.\n" }, "amount_iof": { "type": "number", "example": 100, "description": "The tax amount in local currency (varies between countries).\n" }, "amount_ext": { "type": "number", "example": 100, "description": "The amount in the original currency.\n" }, "currency_rate": { "type": "number", "example": 2.35, "description": "The exchange rate used in the payment.\n" }, "currency_ext": { "type": "string", "example": "BRL", "minLength": 3, "maxLength": 3, "description": "ISO 4217 three letter code of the original currency.\n" }, "due_date": { "type": "string", "example": "2024-01-15", "minLength": 10, "maxLength": 10, "description": "Expiry date of the payment (not applicable to all payment methods).\nFormat: dd/mm/yyyy\n" }, "instalments": { "type": "integer", "example": 1, "description": "Number of instalments for the payment, default value is 1.\n" }, "payment_type_code": { "type": "string", "example": "amex", "minLength": 1, "maxLength": 32, "description": "The code of the payment method. The supported codes are:\n\n- **amex**: American Express credit card (Brazil, Mexico, Colombia).\n- **baloto**: Baloto (Colombia).\n- **bancodobrasil**: Banco do Brasil bank transfer (Brazil).\n- **banrisul**: Banrisul bank transfer (Brazil).\n- **banktransfer**: Bank transfer (Brazil).\n- **boleto**: Boleto bancário (Brazil).\n- **bradesco**: Bradesco bank transfer (Brazil).\n- **carnet**: CARNET credit card (Mexico).\n- **diners**: Diners credit card (Brazil, Colombia).\n- **discover**: Discover credit card (Brazil).\n- **ebanxaccount**: EBANX Account (Brazil).\n- **eft**: Bank Transfer (Colombia).\n- **elo**: Elo credit card (Brazil).\n- **hipercard**: Hipercard credit card (Brazil).\n- **itau**: Itaú bank transfer (Brazil).\n- **mastercard**: MasterCard credit card (Brazil, Mexico, Colombia).\n- **multicaja**: Multicaja (Chile).\n- **oxxo**: OXXO (Mexico).\n- **pagoefectivo**: PagoEfectivo (Peru).\n- **pagosnet**: PagosNet (Bolivia).\n- **paynet**: Paynet (Mexico).\n- **safetypay**: SafetyPay (Peru, Ecuador, Checkout only).\n- **safetypay-cash**: SafetyPay Cash (Peru, Ecuador).\n- **safetypay-online**: SafetyPay Online (Peru, Ecuador).\n- **sencillito**: Sencillito (Chile).\n- **servipag**: Servipag (Chile).\n- **spei**: SPEI bank transfer method (Mexico).\n- **visa**: Visa credit card (Brazil, Mexico, Colombia).\n- **webpay**: Webpay (Chile).\n", "enum": [ "amex", "carnet", "credimas", "diners", "discover", "elo", "hipercard", "mastercard", "naranja", "visa", "baloto", "bancodobrasil", "banktransfer", "banrisul", "boleto", "bradesco", "cupon", "ebanxaccount", "eft", "itau", "multicaja", "oxxo", "pagoefectivo", "pagofacil", "pagosnet", "rapipago", "safetypay", "safetypay-cash", "safetypay-online", "sencillito", "servipag", "spei", "webpay" ] }, "details": { "type": "object", "title": "Details", "description": "A JSON object that represents the payment details.\n", "properties": { "billing_descriptor": { "type": "string", "example": "EBANX*DEMOMERCHANT", "description": "The billing descriptor of the payment.\n" } } }, "transaction_status": { "type": "object", "title": "Transaction Status", "description": "A JSON object that represents the payment credit card transaction.\n", "properties": { "acquirer": { "type": "string", "example": "EBANX", "minLength": 1, "description": "The acquirer that processed the transaction.\n" }, "code": { "type": "string", "example": "OK", "minLength": 2, "maxLength": 7, "description": "The transaction status code:\n\n**OK:** The transaction amount was approved.\n**NOK:** The acquirer did not approved the transaction. The customer must contact the issuer to check for any issue with his credit card.\n**RETRY:** Something went wrong with the process. You can retry with the same data. We recommend you to try more 3 times on different periods of time (first try, then second try after 2 hours after the first, etc).\n" }, "description": { "type": "string", "example": "The transaction was processed successfully", "minLength": 1, "maxLength": 500, "description": "The description for the status code, which is returned from the acquirer.\n" }, "authcode": { "type": "string", "example": "134903", "minLength": 1, "description": "Transaction authentication code in the acquirer.\n" } } }, "pre_approved": { "type": "boolean", "example": true, "description": "Flag that shows if a payment is pre-approved by the credit card acquirer.\n" }, "capture_available": { "type": "boolean", "example": true, "description": "Flag that shows if a payment is ready to be captured. Applies only to credit cards when auto_capture is set to false. Some remarks on this attribute:\n\nA payment can only be captured if pre_approved value is true, which means that the payment has been pre approved by the credit card acquirer. Before capture, an authorized payment has status as PE (pending). After the capture, the status changes to CO (confirmed). A payment can only be captured if the status is PE (pending). *Payments must be captured in 4 (four) days, otherwise they are automatically cancelled.\nNOTE: It can be changed up to 5 (five) days.\n" }, "redirect_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/redirect/payment", "description": "The URL the customer should be redirected to. Applies to certain payment methods using the Direct API.\n" }, "pay_with_balance_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/pay/balance/a1b2c3", "description": "If the customer has an EBANX Account profile and it has balance enough to pay for the created boleto, the response will contain this parameter responsible for redirecting the customer to his EBANX Account page so he can pay the boleto with his available balance.\n" }, "boleto_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/print/?hash=abc123", "description": "The boleto URL.\n" }, "boleto_barcode": { "type": "string", "example": "12345678901234567890123456789012345678901234567", "minLength": 47, "maxLength": 47, "description": "The boleto barcode number. (Boleto)\n" }, "cip_url": { "type": "string", "example": "https://customer.ebanx.com/cip", "description": "The CIP URL. (PagoEfectivo)\n" }, "cip_code": { "type": "string", "example": "123456781234", "minLength": 12, "maxLength": 12, "description": "The CIP code. (PagoEfectivo)\n" }, "refunds": { "type": "array", "description": "An array of objects that represent a refund linked to this payment.\nThis node will only be present if a refund was issued.\n", "items": { "type": "object", "title": "Refunds Item", "properties": { "id": { "type": "integer", "example": 100, "description": "The ID of the refund on EBANX.\n" }, "merchant_refund_code": { "type": "string", "example": "787653", "minLength": 1, "maxLength": 20, "description": "The ID of the refund on the merchant system (optional).\n" }, "status": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "The status of the refund:\n\n**RE (Requested):** The refund has been requested and is waiting to be processed. It can be cancelled while it has this status.\n**PE (Pending):** The refund is being processed. It cannot be cancelled anymore.\n**CO (Confirmed):** The refund was processed and the money was sent back to the customer.\n**CA (Cancelled):** The refund was cancelled.\n" }, "request_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the refund was created. UTC Date.\n" }, "pending_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the customer data was received. UTC Date.\n" }, "confirm_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the money was transferred to the customer. UTC Date.\n" }, "amount_ext": { "type": "number", "example": 100, "description": "The refunded amount in the original currency.\n" }, "description": { "type": "string", "example": "Customer requested a refund", "minLength": 1, "maxLength": 1500, "description": "Description of the refund reason.\n" } } } }, "chargeback": { "type": "object", "title": "Chargeback", "description": "A JSON object that represents a chargeback linked to this payment.\nThis node will only be present if a chargeback was issued.\n", "properties": { "create_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the chargeback was imported into the system. UTC Date.\n" }, "chargeback_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour when the chargeback was created by the acquirer on behalf of the customer. UTC Date.\n" }, "description": { "type": "string", "example": "Chargeback opened by the issuing bank", "minLength": 1, "maxLength": 1500, "description": "Description of the chargeback.\n" } } }, "chargeback_credit": { "type": "boolean", "example": true, "description": "Flag that shows if a chargeback credit was issued.\n" }, "clabe_account": { "type": "string", "example": "646180204800000001", "description": "(Only for SPEI payments) The customer’s CLABE account.\n" }, "clabe_reference": { "type": "string", "example": "1234567", "description": "(Only for SPEI payments) The reference for the current payment.\n" } } } } }, "capture-request": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Capture Request", "description": "Captures a pre-authorized credit card payment.\nOnly applicable when `auto_capture` is set to `false` in the Direct operation\nand the payment has been pre-approved by the acquirer.\n\nThe payment to be captured is identified by either `hash` or `merchant_payment_code`\n(at least one of them is required).\n", "properties": { "hash": { "type": "string", "description": "The payment hash (EBANX unique identifier).\n", "x-conditional": "Required if merchant_payment_code is not provided", "minLength": 48, "maxLength": 48, "example": "5478ba283ef8674415082844ee14817376e49bb76aa9d4c7" }, "merchant_payment_code": { "type": "string", "description": "The payment hash Merchant Payment Code (unique merchant ID).\n", "x-conditional": "Required if hash is not provided", "minLength": 1, "maxLength": 40, "example": "126378126" }, "merchant_capture_code": { "type": "string", "description": "An optional merchant-defined identifier for this specific capture operation.\n", "minLength": 1, "maxLength": 200, "example": "724125124" }, "amount": { "type": "string", "description": "The amount for a partial capture, in the payment's original currency.\nIf omitted or set to `0`, a full capture is performed.\nOnly one partial capture is allowed per authorized payment.\n", "example": "50.00" } }, "anyOf": [ { "required": [ "hash" ] }, { "required": [ "merchant_payment_code" ] } ] }, "payment-response-28": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇦🇷 Argentina", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "cabal": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "naranja": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-29": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇧🇷 Brazil", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "elo": "#/components/schemas/card-response", "hipercard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-30": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇨🇱 Chile", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-31": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇨🇴 Colombia", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "codensa": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "elo": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-32": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇪🇨 Ecuador", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-33": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇲🇽 Mexico", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "carnet": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-34": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇵🇪 Peru", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "payment-response-35": { "x-hidden": true, "x-schema-group": "Responses", "title": "🇺🇾 Uruguay", "oneOf": [ { "$ref": "#/components/schemas/card-response" } ], "discriminator": { "propertyName": "payment_type_code", "mapping": { "amex": "#/components/schemas/card-response", "creditcard": "#/components/schemas/card-response", "creditel": "#/components/schemas/card-response", "debitcard": "#/components/schemas/card-response", "diners": "#/components/schemas/card-response", "lider": "#/components/schemas/card-response", "mastercard": "#/components/schemas/card-response", "oca": "#/components/schemas/card-response", "visa": "#/components/schemas/card-response" } } }, "capture-payment-response": { "x-hidden": true, "x-schema-group": "Responses", "title": "Capture Payment Response", "description": "The payment response object returned by the capture endpoint. Because capture only applies\nto credit card payments, this union includes only the card-supporting countries and resolves\neach to its card-only response variant. Structure varies by country.\n", "oneOf": [ { "$ref": "#/components/schemas/payment-response-28" }, { "$ref": "#/components/schemas/payment-response-29" }, { "$ref": "#/components/schemas/payment-response-30" }, { "$ref": "#/components/schemas/payment-response-31" }, { "$ref": "#/components/schemas/payment-response-6" }, { "$ref": "#/components/schemas/payment-response-7" }, { "$ref": "#/components/schemas/payment-response-32" }, { "$ref": "#/components/schemas/payment-response-11" }, { "$ref": "#/components/schemas/payment-response-33" }, { "$ref": "#/components/schemas/payment-response-17" }, { "$ref": "#/components/schemas/payment-response-34" }, { "$ref": "#/components/schemas/payment-response-20" }, { "$ref": "#/components/schemas/payment-response-21" }, { "$ref": "#/components/schemas/payment-response-35" } ], "discriminator": { "propertyName": "country", "mapping": { "ar": "#/components/schemas/payment-response-28", "br": "#/components/schemas/payment-response-29", "cl": "#/components/schemas/payment-response-30", "co": "#/components/schemas/payment-response-31", "cr": "#/components/schemas/payment-response-6", "do": "#/components/schemas/payment-response-7", "ec": "#/components/schemas/payment-response-32", "gt": "#/components/schemas/payment-response-11", "mx": "#/components/schemas/payment-response-33", "pa": "#/components/schemas/payment-response-17", "pe": "#/components/schemas/payment-response-34", "py": "#/components/schemas/payment-response-20", "sv": "#/components/schemas/payment-response-21", "uy": "#/components/schemas/payment-response-35" } } }, "capture-response": { "x-schema-group": "Responses", "title": "Capture Response", "type": "object", "description": "JSON object returned when a payment is successfully captured.\nBecause capture only applies to credit card payments, the payment object uses a dedicated,\ncard-only response union that includes only the card-supporting countries and resolves each\nto its card payment variant.\n", "properties": { "status": { "type": "string", "description": "The status of the request (SUCCESS or ERROR).\n", "example": "SUCCESS", "minLength": 5, "maxLength": 7 }, "payment": { "title": "Payment", "description": "A JSON object that represents the captured payment.\nReturns only card payment variants for the card-supporting countries.\n", "allOf": [ { "$ref": "#/components/schemas/capture-payment-response" }, { "$ref": "#/components/schemas/customization-extras" }, { "type": "object", "title": "Capture Payment Extra", "properties": { "customer": { "$ref": "#/components/schemas/customer" } } } ] } } }, "capture-error-code": { "title": "Capture Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Capture-specific error codes returned by the Capture API endpoint.\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-CAP-1" ], "description": "Parameters hash or merchant_payment_code not informed." }, { "enum": [ "BP-CAP-2" ], "description": "Payment not found for the merchant." }, { "enum": [ "BP-CAP-3" ], "description": "Payment cannot be captured because its status is cancelled (CA)." }, { "enum": [ "BP-CAP-4" ], "description": "Payment has already been captured and its status is confirmed (CO)." }, { "enum": [ "BP-CAP-5" ], "description": "Payment cannot be captured because its status is open (OP)." }, { "enum": [ "BP-CAP-6" ], "description": "Payment cannot be captured because the payment type does not support capture." }, { "enum": [ "BP-CAP-7" ], "description": "Payment cannot be captured because auto_capture is enabled." }, { "enum": [ "BP-CAP-8" ], "description": "Payment cannot be captured because capture_available is false." }, { "enum": [ "BP-CAP-9" ], "description": "Payment cannot be captured because pre_approved is false." }, { "enum": [ "BP-CAP-10" ], "description": "Invalid partial capture amount." }, { "enum": [ "BP-CAP-11" ], "description": "Partial capture not available for this payment." }, { "enum": [ "BP-CAP-12" ], "description": "Partial capture amount exceeds the maximum allowed amount." }, { "enum": [ "BP-CAP-13" ], "description": "Split not informed on the partial capture of a payment authorized with split." }, { "enum": [ "BP-CAP-14" ], "description": "The sum of the split amounts is different from the captured amount." }, { "enum": [ "BP-CAP-15" ], "description": "One or more split amounts are not positive." }, { "enum": [ "BP-CAP-16" ], "description": "The same recipient_code was informed more than once on the split." }, { "enum": [ "BP-CAP-17" ], "description": "One or more split recipients do not exist in the original payment." }, { "enum": [ "BP-CAP-18" ], "description": "Liability or fee responsibility cannot be changed on capture." }, { "enum": [ "BP-CAP-19" ], "description": "The split percentages are not positive or do not add up to 100%." }, { "enum": [ "BP-CAP-20" ], "description": "The split mixes amount and percentage allocations, or a rule has neither of them." } ], "example": "BP-CAP-2" }, "capture-error-response": { "x-schema-group": "Responses", "title": "Capture Error Response", "description": "Error response returned when a capture request fails (e.g. payment not found, payment cannot be\ncaptured in its current status, or an authentication error).\n", "type": "object", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/capture-error-code" }, { "$ref": "#/components/schemas/auth-error-code" }, { "$ref": "#/components/schemas/api-error-code" } ], "description": "The error code identifying what went wrong. Includes Capture-specific, Authentication and API-wide error codes.\n", "example": "BP-CAP-2" }, "status_message": { "type": "string", "description": "A human-readable error message describing what went wrong.\n", "example": "Payment not found for merchant" } } }, "available-ewallets-request": { "type": "object", "title": "Available E-Wallets Request", "x-schema-group": "Requests", "description": "Request body for the available e-wallets query.\n", "required": [ "country" ], "properties": { "country": { "type": "string", "description": "The two-letter country code (ISO 3166-1 alpha-2) for which to retrieve available e-wallets.\nThe server validates the country dynamically; availability depends on merchant configuration.\n", "minLength": 2, "maxLength": 2, "example": "co" } } }, "available-ewallets-success-response": { "title": "Available E-Wallets Success Response", "x-schema-group": "Responses", "type": "array", "description": "List of e-wallets available for the requested country.\nReturns an empty array when no e-wallets are available.\n", "items": { "title": "Available E-Wallet Item", "type": "object", "description": "An e-wallet available for the requested country.\n", "required": [ "code", "name", "icon_url", "promotional_text" ], "properties": { "code": { "type": "string", "description": "The e-wallet payment type code, usable as `payment_type_code` in the Direct API.\n", "example": "nequi" }, "name": { "type": "string", "description": "The commercial display name of the e-wallet.\n", "example": "Nequi" }, "icon_url": { "type": "string", "description": "URL of the official e-wallet logo.\n", "example": "https://sandbox.ebanxpay.com/assets/nequi/icon.png" }, "promotional_text": { "type": "string", "description": "Promotional text configured for the e-wallet. Empty string when not configured.\n", "example": "Get 10% cashback on your next purchase" } } } }, "available-ewallets-error-code": { "title": "Available E-Wallets Error Code", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to the `/ws/ewallet-availableEWallets` endpoint.\n", "oneOf": [ { "enum": [ "BP-DR-77" ], "description": "The specified country is not enabled or not found." }, { "enum": [ "BP-DR-132" ], "description": "The country field is required." } ], "example": "BP-DR-132" }, "available-ewallets-error-response": { "title": "Available E-Wallets Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the request fails validation or authentication.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "Indicates the request resulted in an error.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/available-ewallets-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code identifying what went wrong. Includes endpoint-specific (BP-DR-*) and authentication (BP-SA-*) error codes.\n", "example": "BP-DR-132" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Field country is required" } } }, "request-body": { "type": "object", "title": "ws/request", "description": "This method allows you to create a payment using EBANX Payment Page, where the customer is redirected to EBANX’s website to enter his data.\n", "required": [ "name", "email", "currency_code", "amount", "payment_type_code", "country" ], "properties": { "name": { "type": "string", "description": "Customer name.", "minLength": 1, "maxLength": 100, "example": "José Silva" }, "email": { "type": "string", "description": "Customer email address.", "minLength": 5, "maxLength": 100, "example": "josesilva@example.com" }, "currency_code": { "type": "string", "description": "Three-letter code of the payment currency. Supported currencies:\n\n- EUR\n- BRL\n- MXN\n- PEN\n- USD\n- CLP\n- COP\n- ARS\n- BOB\n", "enum": [ "ARS", "BOB", "BRL", "CLP", "COP", "EUR", "MXN", "PEN", "USD" ], "example": "BRL", "minLength": 3, "maxLength": 3 }, "amount": { "type": "number", "description": "The amount in the specified currency (currency_code).", "example": "100" }, "merchant_payment_code": { "type": "string", "description": "The payment hash Merchant Payment Code (unique merchant ID).\n", "example": "d59cb7166e7" }, "order_number": { "example": "order_66", "type": "string", "description": "The order number, optional identifier set by the merchant. \nYou can have multiple payments with the same order number.\n", "minLength": 1, "maxLength": 40 }, "payment_type_code": { "type": "string", "description": "The code of the payment method. The supported codes are:\n\n- **_all:** all available payment methods for the merchant account in this country.\n- **amex:** American Express credit card (Brazil, Mexico, Colombia, Peru).\n- **bancodobrasil:** Banco do Brasil online debit (Brazil).\n- **banrisul:** Banrisul online debit (Brazil).\n- **banktransfer:** Bank transfer (Brazil).\n- **boleto:** Boleto bancário (Brazil).\n- **bradesco:** Bradesco online debit (Brazil).\n- **carnet:** CARNET credit card (Mexico).\n- **diners:** Diners credit card (Brazil, Colombia, Peru).\n- **discover:** Discover credit card (Brazil).\n- **ebanxaccount:** EBANX Account (Brazil).\n- **eft:** Bank Transfer (Colombia).\n- **elo:** Elo credit card (Brazil).\n- **hipercard:** Hipercard credit card (Brazil).\n- **itau:** Itaú online debit (Brazil).\n- **mastercard:** MasterCard credit card (Brazil, Mexico, Colombia, Peru).\n- **multicaja:** Multicaja (Chile).\n- **oxxo:** OXXO (Mexico).\n- **pagoefectivo:** PagoEfectivo (Peru).\n- **pagosnet:** PagosNet (Bolivia).\n- **safetypay:** SafetyPay (Peru, Ecuador, Checkout only).\n- **safetypay-cash:** SafetyPay Cash (Peru, Ecuador).\n- **safetypay-online:** SafetyPay Online (Peru, Ecuador).\n- **sencillito:** Sencillito (Chile).\n- **servipag:** Servipag (Chile).\n- **spei:** SPEI bank transfer method (Mexico).\n- **visa:** Visa credit card (Brazil, Mexico, Colombia, Peru).\n- **webpay:** Webpay (Chile).\n", "minLength": 1, "maxLength": 32, "enum": [ "_all", "amex", "carnet", "diners", "discover", "elo", "hipercard", "mastercard", "visa", "bancodobrasil", "banktransfer", "banrisul", "boleto", "bradesco", "ebanxaccount", "eft", "itau", "multicaja", "oxxo", "pagoefectivo", "pagosnet", "safetypay", "safetypay-cash", "safetypay-online", "sencillito", "servipag", "spei", "webpay" ], "example": "_all" }, "notification_url": { "example": "https://notify.example.com/", "type": "string", "description": "The URL to send notifications for this payment. \nIf this field is filled, EBANX will notify using this URL instead of the configured one.\nExample: https://notify.example.com/\n", "minLength": 1, "maxLength": 2000 }, "bypass_boleto_screen": { "type": "boolean", "example": true, "description": "Optional parameter to tell EBANX to redirect the customer straight to the response URL after the payment is completed. This can be used in cases where the merchant will provide all the payment information in the response URL page.\nIf this parameter is passed and equals to true then EBANX will not display the payment completed screen and will redirect the customer straight to the response URL, where the merchant must provide all the payment information. If the parameter is not provided or its value is not true, the payment completed screen will be displayed.\n" }, "zipcode": { "type": "string", "description": "Customer zipcode. If provided, the information will be displayed in the EBANX Payment Page.\n", "minLength": 8, "maxLength": 8, "example": "61919230" }, "street_number": { "type": "string", "description": "Customer street number. If provided, the information will be displayed in the EBANX Payment Page.", "example": "1040", "minLength": 1, "maxLength": 30 }, "city": { "type": "string", "description": "Customer city. If provided, the information will be displayed in the EBANX Payment Page.", "example": "Maracanau", "minLength": 1, "maxLength": 80 }, "state": { "type": "string", "description": "Customer state/region/province. If provided, the information will be displayed in the EBANX Payment Page.\n", "example": "CE" }, "country": { "type": "string", "description": "The two-letter country code for the customer country. The available codes are:\n \n- **bo**: Bolivia.\n- **br**: Brazil.\n- **cl**: Chile.\n- **co**: Colombia.\n- **mx**: Mexico.\n- **pe**: Peru.\n- **ar**: Argentina.\n- **ec**: Ecuador.\n", "enum": [ "ar", "bo", "br", "cl", "co", "ec", "mx", "pe" ], "example": "br" }, "phone_number": { "type": "string", "description": "Customer phone number. If provided, the information will be displayed in the EBANX Payment Page.", "minLength": 10, "maxLength": 15, "example": 8522847035 }, "due_date": { "example": "2024-12-20", "type": "string", "description": "The due date of payments slips. Due date for boleto payments. The maximum expiry date will depend on your merchant account settings.The due date is based on the local time of the country that the payment is generated.\n", "minLength": 10, "maxLength": 10 }, "sub_acc_name": { "example": "account_name", "type": "string", "description": "The name of the sub account.\n", "minLength": 1, "maxLength": 32 }, "sub_acc_image_url": { "example": "https://example.com/image.png", "type": "string", "description": "The URL of the logo of the sub account. \nOBS: It MUST be a HTTPS URL, otherwise, you will receive and error message.\n", "minLength": 1, "maxLength": 200 }, "instalments": { "example": "1", "type": "string", "description": "Number or Range of instalments. \nOBS: If your are sending a range, must be in the format “X-Y”. Example: “1-6”.\n", "minLength": 1, "maxLength": 5 } } }, "request-response": { "title": "Request Response", "type": "object", "description": "JSON object with the payment data.\nThe response parameters will vary depending on the chosen payment method.\n", "properties": { "status": { "type": "string", "example": "SUCCESS", "description": "The status of the the request (SUCCESS or ERROR).\n", "minLength": 5, "maxLength": 7 }, "payment": { "type": "object", "title": "Payment", "description": "A JSON object that represents the payment.\n", "properties": { "hash": { "type": "string", "example": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221", "minLength": 48, "maxLength": 48, "description": "The payment hash (EBANX unique identifier).\n" }, "country": { "type": "string", "example": "br", "minLength": 2, "maxLength": 2, "description": "The country of the payment.\n" }, "merchant_payment_code": { "type": "string", "example": "merchant-payment-code-123", "minLength": 1, "maxLength": 40, "description": "The payment hash Merchant Payment Code (unique merchant ID).\n" }, "status": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "The payment status. The following statuses are available:\n\n- **OP**: the customer has not yet filled the payment details on the EBANX Checkout. It can change either to CA (time out) or PE.\n- **PE**: the payment is pending confirmation. It can change either to CA or CO.\n- **CO**: the payment is confirmed (paid).\n- **CA**: the payment is cancelled.\n" }, "status_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of the last status change.\n" }, "open_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was created.\n" }, "confirm_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was confirmed.\n" }, "transfer_date": { "type": "string", "example": "2024-01-15 10:30:00", "minLength": 19, "maxLength": 19, "description": "The date and hour of when the payment was settled.\n" }, "amount_br": { "type": "number", "example": 100, "description": "The amount in local currency.\n" }, "amount_ext": { "type": "number", "example": 100, "description": "The amount in the original currency.\n" }, "currency_rate": { "type": "number", "example": 2.35, "description": "The exchange rate used in the payment.\n" }, "currency_ext": { "type": "string", "example": "BRL", "minLength": 3, "maxLength": 3, "description": "ISO 4217 three letter code of the original currency.\n" }, "due_date": { "type": "string", "example": "2024-01-15", "minLength": 10, "maxLength": 10, "description": "Expiry date of the payment (not applicable to all payment methods).\nFormat: dd/mm/yyyy\n" }, "instalments": { "type": "integer", "example": 1, "description": "Number of instalments for the payment, default value is 1.\n" }, "payment_type_code": { "type": "string", "example": "amex", "minLength": 1, "maxLength": 32, "description": "The code of the payment method. The supported codes are:\n\n- **amex**: American Express credit card (Brazil, Mexico, Colombia).\n- **bancodobrasil**: Banco do Brasil bank transfer (Brazil).\n- **banrisul**: Banrisul bank transfer (Brazil).\n- **banktransfer**: Bank transfer (Brazil).\n- **boleto**: Boleto bancário (Brazil).\n- **bradesco**: Bradesco bank transfer (Brazil).\n- **carnet**: CARNET credit card (Mexico).\n- **diners**: Diners credit card (Brazil, Colombia).\n- **discover**: Discover credit card (Brazil).\n- **ebanxaccount**: EBANX Account (Brazil).\n- **eft**: Bank Transfer (Colombia).\n- **elo**: Elo credit card (Brazil).\n- **hipercard**: Hipercard credit card (Brazil).\n- **itau**: Itaú bank transfer (Brazil).\n- **mastercard**: MasterCard credit card (Brazil, Mexico, Colombia).\n- **multicaja**: Multicaja (Chile).\n- **oxxo**: OXXO (Mexico).\n- **pagoefectivo**: PagoEfectivo (Peru).\n- **pagosnet**: PagosNet (Bolivia).\n- **paynet**: Paynet (Mexico).\n- **safetypay**: SafetyPay (Peru, Ecuador, Checkout only).\n- **safetypay-cash**: SafetyPay Cash (Peru, Ecuador).\n- **safetypay-online**: SafetyPay Online (Peru, Ecuador).\n- **sencillito**: Sencillito (Chile).\n- **servipag**: Servipag (Chile).\n- **spei**: SPEI bank transfer method (Mexico).\n- **visa**: Visa credit card (Brazil, Mexico, Colombia).\n- **webpay**: Webpay (Chile).\n", "enum": [ "amex", "carnet", "credimas", "diners", "discover", "elo", "hipercard", "mastercard", "naranja", "visa", "bancodobrasil", "banktransfer", "banrisul", "boleto", "bradesco", "cupon", "ebanxaccount", "eft", "itau", "multicaja", "oxxo", "pagoefectivo", "pagofacil", "pagosnet", "rapipago", "safetypay", "safetypay-cash", "safetypay-online", "sencillito", "servipag", "spei", "webpay" ] }, "transaction_status": { "type": "object", "title": "Transaction Status", "description": "A JSON object that represents the payment credit card transaction.\n", "properties": { "acquirer": { "type": "string", "example": "EBANX", "minLength": 1, "description": "The acquirer that processed the transaction.\n" }, "code": { "type": "string", "example": "OK", "minLength": 2, "maxLength": 7, "description": "The transaction status code:\n\n**OK:** The transaction amount was approved.\n**NOK:** The acquirer did not approved the transaction. The customer must contact the issuer to check for any issue with his credit card.\n**RETRY:** Something went wrong with the process. You can retry with the same data. We recommend you to try more 3 times on different periods of time (first try, then second try after 2 hours after the first, etc).\n" }, "description": { "type": "string", "example": "The transaction was processed successfully", "minLength": 1, "maxLength": 500, "description": "The description for the status code, which is returned from the acquirer.\n" }, "authcode": { "type": "string", "example": "134903", "minLength": 1, "description": "Transaction authentication code in the acquirer.\n" } } }, "pre_approved": { "type": "boolean", "example": true, "description": "Flag that shows if a payment is pre-approved by the credit card acquirer.\n" }, "redirect_url": { "type": "string", "example": "https://sandbox.ebanxpay.com/redirect/payment", "description": "The URL the customer should be redirected to. Applies to certain payment methods using the Direct API.\n" } } } } }, "exchange-request": { "type": "object", "title": "Exchange Request", "description": "Request body for the exchange rate query. Queries EBANX for the current exchange rate for a given currency pair.\n", "required": [ "currency_code" ], "properties": { "currency_code": { "type": "string", "description": "The source currency to query (ISO 4217 three-letter code).\nValidated against FX Token allowed base currencies: USD, EUR, GBP, CCL.\n", "minLength": 3, "maxLength": 3, "example": "USD" }, "currency_base_code": { "type": "string", "description": "The target (base) currency (ISO 4217 three-letter code). Defaults to BRL if not provided.\nValidated against FX Token allowed target currencies. If invalid, the request fails with `BP-EX-2`.\n", "minLength": 3, "maxLength": 3, "default": "BRL", "example": "BRL" } } }, "currency-rate": { "x-hidden": true, "title": "Currency Rate", "type": "object", "description": "The currency rate details for a currency pair.\n", "required": [ "code", "base_code", "name", "rate" ], "properties": { "code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The source currency code (ISO 4217 three-letter code).\n", "example": "USD" }, "base_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The target (base) currency code (ISO 4217 three-letter code).\n", "example": "BRL" }, "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The name of the currency rate.\n", "example": "Real to US Dollar" }, "rate": { "type": "string", "description": "The current exchange rate as a decimal string.\n", "example": "2.7731" } } }, "exchange-response": { "title": "Exchange Success Response", "type": "object", "description": "Success response for the exchange rate query. Contains the currency rate details and operation status.\n", "required": [ "status", "currency_rate" ], "properties": { "status": { "type": "string", "description": "The status of the API request.\n", "enum": [ "SUCCESS" ], "example": "SUCCESS" }, "currency_rate": { "$ref": "#/components/schemas/currency-rate" } } }, "exchange-error-code": { "title": "Exchange Error Code", "type": "string", "description": "Exchange-specific error codes returned by `/ws/exchange` and related sub-endpoints.\n", "oneOf": [ { "enum": [ "BP-EX-1" ], "description": "Currency code not informed." }, { "enum": [ "BP-EX-2" ], "description": "Currency is not active or not allowed for FX Token." } ], "example": "BP-EX-2" }, "exchange-error-response": { "title": "Exchange Error Response", "type": "object", "description": "Error response returned when the exchange rate query fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/exchange-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code. Can be an exchange-specific code (BP-EX-*) or an authentication code (BP-SA-*).\n", "example": "BP-EX-2" }, "status_message": { "type": "string", "description": "A human-readable error message describing what went wrong.\n", "example": "Currency is not active in the system: AUD" } } }, "get-currency-rates-request": { "type": "object", "title": "Get Currency Rates Request", "description": "Request body to query multiple currency exchange rates at once. Accepts arrays of currency codes and returns all valid pairs. Invalid or inactive pairs are silently excluded from the response.\n", "required": [ "currency_codes" ], "properties": { "currency_codes": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 3 }, "description": "The source currency code(s) to query (ISO 4217 three-letter codes).\nEmpty strings in the array are filtered out before processing.\n", "example": [ "USD", "EUR" ] }, "currency_base_codes": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 3 }, "description": "The target (base) currency code(s) (ISO 4217 three-letter codes).\nEmpty strings in the array are filtered out. Defaults to `[\"BRL\"]` if omitted or all entries are empty.\n", "default": [ "BRL" ], "example": [ "BRL", "CLP" ] } } }, "get-currency-rates-response": { "title": "Get Currency Rates Success Response", "type": "object", "description": "Response containing multiple currency exchange rates. Returns all valid currency pairs from the requested combinations.\n", "required": [ "status", "currency_rates" ], "properties": { "status": { "type": "string", "description": "The status of the API request.\n", "enum": [ "SUCCESS" ], "example": "SUCCESS" }, "currency_rates": { "type": "array", "description": "Array of currency rate objects. Pairs where code equals base_code, or where the currency is inactive/not found, are silently excluded.\n", "items": { "$ref": "#/components/schemas/currency-rate" } } } }, "get-currency-rates-error-response": { "title": "Get Currency Rates Error Response", "type": "object", "description": "Error response returned when the getCurrencyRates request fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "type": "string", "description": "Exchange-specific error code.\n- **BP-EX-2** - Currency codes not informed (only BP-EX-2 is returned by this subendpoint, not BP-EX-1).\n", "enum": [ "BP-EX-2" ] }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code. Can be an exchange-specific code (BP-EX-*) or an authentication code (BP-SA-*).\n", "example": "BP-EX-2" }, "status_message": { "type": "string", "description": "A human-readable error message.\n", "example": "Currency codes not informed" } } }, "fxtoken-request": { "title": "FX Token Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for retrieving a fixed exchange rate token for a currency pair.\n", "required": [ "currency_from", "currency_to" ], "properties": { "country": { "type": "string", "description": "The two-letter country code (ISO 3166-1 alpha-2, lowercase) where the operation is being processed.\n", "enum": [ "ar", "bo", "br", "cl", "co", "mx", "pe" ], "minLength": 2, "maxLength": 2, "example": "br" }, "currency_from": { "type": "string", "description": "The three-letter currency code (ISO 4217) of the source currency from which the amount will be converted.\n", "enum": [ "EUR", "GBP", "USD" ], "minLength": 3, "maxLength": 3, "example": "USD" }, "currency_to": { "type": "string", "description": "The three-letter currency code (ISO 4217) of the target currency to which the amount will be converted.\n", "enum": [ "ARS", "BOB", "BRL", "CLP", "COP", "CRC", "DOP", "EGP", "GBP", "GTQ", "IDR", "INR", "KES", "MXN", "NGN", "PAB", "PEN", "PYG", "USD", "UYU", "ZAR" ], "minLength": 3, "maxLength": 3, "example": "BRL" } } }, "fxtoken-success-response": { "title": "FX Token Success Response", "x-schema-group": "Responses", "type": "object", "description": "Successful response containing the fixed exchange rate token and its details.\n", "required": [ "fx_token", "currency_rate", "currency_from", "currency_to", "expire_date", "new_currency_rate_available_at" ], "properties": { "fx_token": { "type": "string", "description": "The unique token identifier to be used in subsequent payment operations\nthat require a fixed exchange rate.\n", "example": "69e2ca74029c41a9016009b67f8a3256d595ebbb54c79f1014" }, "currency_rate": { "type": "string", "description": "The fixed exchange rate that will be applied when this token is used.\nReturned as a string to preserve decimal precision.\n", "example": "5.2764" }, "currency_from": { "type": "string", "description": "The source currency code (ISO 4217) as provided in the request.\n", "minLength": 3, "maxLength": 3, "example": "USD" }, "currency_to": { "type": "string", "description": "The target currency code (ISO 4217) as provided in the request.\n", "minLength": 3, "maxLength": 3, "example": "BRL" }, "expire_date": { "type": "string", "format": "date-time", "description": "The UTC date and time when this token expires and can no longer be used.\n", "example": "2026-04-18T18:59:59+00:00" }, "new_currency_rate_available_at": { "type": "string", "format": "date-time", "description": "The UTC date and time when the next token becomes available. A new token is always\navailable before the current token expires, creating an overlap period where both\ntokens are valid.\n", "example": "2026-04-18T18:58:59+00:00" } } }, "fxtoken-error-code": { "title": "FX Token Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to the `/ws/fxtoken/get` endpoint.\n", "oneOf": [ { "enum": [ "BP-DR-109" ], "description": "The FX Token feature is not enabled for the merchant account." }, { "enum": [ "BP-DR-110" ], "description": "The requested currency pair is invalid or not supported." } ], "example": "BP-DR-110" }, "fxtoken-error-response": { "title": "FX Token Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the FX token request fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the response.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "description": "A machine-readable error code identifying the specific error.\n", "oneOf": [ { "$ref": "#/components/schemas/fxtoken-error-code" }, { "$ref": "#/components/schemas/auth-error-code" }, { "$ref": "#/components/schemas/api-error-code" } ], "example": "BP-DR-110" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "FX Token: Base currency not enabled." } } }, "token-request": { "title": "Token Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for the token creation operation.\n", "required": [ "creditcard", "payment_type_code" ], "properties": { "public_integration_key": { "type": "string", "description": "Your unique and public integration key. Use this key instead of the `integration_key` when the request originates from the client side (browser, mobile app).\n", "minLength": 1, "maxLength": 100, "example": "your_test_public_integration_key" }, "payment_type_code": { "type": "string", "description": "The credit card scheme.\n", "enum": [ "amex", "aura", "carnet", "debitcard", "diners", "discover", "elo", "hipercard", "mastercard", "sodexo", "visa" ], "minLength": 1, "maxLength": 32, "example": "visa" }, "token": { "type": "string", "description": "A custom token value. Set this if you want to provide your own token instead of letting EBANX generate one.\n", "minLength": 32, "maxLength": 128, "example": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" }, "country": { "type": "string", "description": "The two-letter country code for the customer's country (ISO 3166-1 alpha-2). If not provided, the system attempts to detect the country from the card BIN.\n", "minLength": 2, "maxLength": 2, "example": "br" }, "creditcard": { "type": "object", "title": "Credit Card", "description": "The credit card details.\n", "required": [ "card_number", "card_name", "card_due_date" ], "properties": { "card_number": { "type": "string", "description": "The credit card number (must pass Luhn validation).\n", "minLength": 14, "maxLength": 19, "example": "4111111111111111" }, "card_name": { "type": "string", "description": "The cardholder name as printed on the credit card. Must not contain numbers.\n", "minLength": 1, "maxLength": 64, "example": "Jose da Silva" }, "card_due_date": { "type": "string", "description": "The credit card expiration date.\n", "pattern": "^\\d{2}/\\d{4}$", "minLength": 7, "maxLength": 7, "example": "12/2028" }, "card_cvv": { "type": "string", "description": "The Card Verification Value (3-4 digits).\n", "x-conditional": "Required unless the merchant has CVV-optional configuration enabled", "minLength": 3, "maxLength": 4, "example": "123" }, "threeds_force": { "type": "string", "description": "When set to `\"true\"`, forces 3D Secure authentication during token creation.\n", "enum": [ "false", "true" ], "example": "false" } } }, "verify_card": { "type": "boolean", "description": "When set to `true`, EBANX performs a card verification (zero-dollar authorization or ghost authorization) to confirm the card is valid before creating the token.\n", "default": false, "example": false }, "redirect_url": { "type": "string", "description": "The URL to redirect the customer back to after 3D Secure authentication is complete.\n", "x-conditional": "Required when creditcard.threeds_force is set to \"true\"", "format": "uri", "example": "https://merchant.com/callback" }, "customer": { "type": "object", "title": "Customer", "description": "Customer details used for 3D Secure authentication.\n", "properties": { "document": { "type": "string", "description": "The customer's document number (CPF, CNPJ, etc.).\n", "example": "12345678901" }, "document_type": { "type": "string", "description": "The type of document provided.\n", "example": "cpf" }, "email": { "type": "string", "description": "The customer's email address.\n", "format": "email", "example": "jose@example.com" }, "address": { "type": "string", "description": "The customer's street address.\n", "example": "Rua E" }, "city": { "type": "string", "description": "The customer's city.\n", "example": "Maringá" }, "state": { "type": "string", "description": "The customer's state or region.\n", "example": "PR" }, "zipcode": { "type": "string", "description": "The customer's postal code.\n", "example": "87080000" }, "country": { "type": "string", "description": "The customer's country code (ISO 3166-1 alpha-2).\n", "minLength": 2, "maxLength": 2, "example": "br" }, "phone_number": { "type": "string", "description": "The customer's phone number.\n", "example": "5544999887766" } } } } }, "network-token-status": { "title": "Network Token Status", "x-schema-group": "Response Codes", "type": "string", "description": "Provisioning status of a network token associated with a card token.\n", "oneOf": [ { "enum": [ "ACTIVE" ], "description": "The network token is active and ready for use in transactions." }, { "enum": [ "DELETED" ], "description": "The network token has been deleted." }, { "enum": [ "FAILED_REQUEST" ], "description": "The network token provisioning request failed." }, { "enum": [ "NOT_FOUND" ], "description": "No network token was found for this card token." }, { "enum": [ "NOT_PROVISIONED" ], "description": "The network token has not been provisioned yet." }, { "enum": [ "SUSPENDED" ], "description": "The network token is temporarily suspended." }, { "enum": [ "UNKNOWN" ], "description": "The network token status could not be determined." }, { "enum": [ "WAIT_PROVISIONING" ], "description": "The network token is being provisioned." } ], "example": "ACTIVE" }, "card-verification": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Card Verification", "description": "Card verification results from ghost authorization or zero-dollar verification, when available.\n", "properties": { "transaction_status": { "type": "object", "title": "Transaction Status", "description": "The status of the card verification transaction.\n", "properties": { "code": { "type": "string", "description": "The verification result code.\n", "enum": [ "3DS_PENDING", "NA", "NOK", "OK", "OTP_PENDING" ], "example": "OK" }, "description": { "type": "string", "description": "A human-readable description of the verification result.\n", "example": "Accepted" } } }, "transaction_type": { "type": "string", "description": "The type of verification transaction performed.\n", "enum": [ "GHOST AUTHORIZATION", "ZERO DOLLAR" ], "example": "ZERO DOLLAR" }, "status_otp": { "type": "string", "description": "The OTP authentication status, when available.\n", "example": "authenticated" } } }, "token-success-response": { "title": "Token Success Response", "x-schema-group": "Responses", "type": "object", "description": "Successful response when a card token is created.\n", "required": [ "status", "payment_type_code", "token", "masked_card_number" ], "properties": { "status": { "type": "string", "enum": [ "SUCCESS" ], "description": "Indicates the operation was successful.\n", "example": "SUCCESS" }, "payment_type_code": { "type": "string", "description": "The credit card scheme used for tokenization.\n", "minLength": 1, "maxLength": 32, "example": "visa" }, "token": { "type": "string", "description": "The generated token, or the same custom token value that was provided in the request.\n", "minLength": 32, "maxLength": 128, "example": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6" }, "masked_card_number": { "type": "string", "description": "The masked credit card number.\n", "minLength": 14, "maxLength": 19, "example": "411111xxxxxx1111" }, "brand": { "type": "string", "nullable": true, "description": "The detected card brand/scheme, when available.\n", "example": "visa" }, "network_token_status": { "description": "The provisioning status of a network token for this card, when available.\n", "allOf": [ { "$ref": "#/components/schemas/network-token-status" } ], "example": "ACTIVE" }, "card_unique_id": { "type": "string", "description": "A unique identifier for the physical card, when available.\n", "example": "abc123def456" }, "card_verification": { "$ref": "#/components/schemas/card-verification" }, "threedsecure": { "type": "object", "title": "3D Secure", "description": "3D Secure authentication details, when available.\n", "properties": { "status": { "description": "The current status of the 3D Secure authentication process.\n", "allOf": [ { "$ref": "#/components/schemas/threeds-authentication-status" } ], "example": "PENDING_AUTHENTICATION" }, "threeds_redirect_url": { "type": "string", "description": "The URL to redirect the customer to for 3D Secure authentication.\n", "format": "uri", "example": "https://sandbox.ebanxpay.com/ws/threedsecureredirect/initAuth?id=abc123" } } } } }, "token-error-code": { "title": "Token Error Code", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to the token endpoints (/ws/token, /ws/token/setCVV, /ws/token/query, /ws/token/delete).\n", "oneOf": [ { "enum": [ "BP-3DSR-10" ], "description": "The redirect_url field is required for 3DS authentication." }, { "enum": [ "BP-DR-35" ], "description": "Card BIN not found or the payment type code provided is invalid." }, { "enum": [ "BP-DR-36" ], "description": "The payment type is not active or not enabled for this merchant/country." }, { "enum": [ "BP-DR-38" ], "description": "The payment type is not enabled for this merchant." }, { "enum": [ "BP-DR-48" ], "description": "The creditcard object is required but was not provided in the request." }, { "enum": [ "BP-DR-49" ], "description": "The card_number field inside the creditcard object is required." }, { "enum": [ "BP-DR-51" ], "description": "The card_name field inside the creditcard object is required." }, { "enum": [ "BP-DR-54" ], "description": "The card_cvv field is required." }, { "enum": [ "BP-DR-55" ], "description": "The card_cvv value provided is invalid (must be 3-4 digits)." }, { "enum": [ "BP-DR-56" ], "description": "The card_due_date field inside the creditcard object is required." }, { "enum": [ "BP-DR-61" ], "description": "It was not possible to create the token for this credit card." }, { "enum": [ "BP-DR-64" ], "description": "The specified token was not found." }, { "enum": [ "BP-DR-65" ], "description": "The provided custom token value is already in use by another card." }, { "enum": [ "BP-DR-66" ], "description": "The custom token value is not valid. Token length must be between 32 and 128 characters." }, { "enum": [ "BP-DR-67" ], "description": "The card expiration date is invalid or expired." }, { "enum": [ "BP-DR-75" ], "description": "The card number is invalid (failed Luhn check or incorrect format)." }, { "enum": [ "BP-DR-77" ], "description": "The country specified is not enabled." }, { "enum": [ "BP-DR-78" ], "description": "The country or payment type is not enabled for this merchant." }, { "enum": [ "BP-DR-83" ], "description": "Foreign credit cards cannot be processed for this country/merchant." }, { "enum": [ "BP-DR-95" ], "description": "The cardholder name must be a valid name and cannot contain numbers." }, { "enum": [ "BP-DR-101" ], "description": "The card is not eligible for e-commerce transactions." }, { "enum": [ "BP-DR-176" ], "description": "Card verification is not enabled for this merchant." }, { "enum": [ "BP-DR-208" ], "description": "The integration key is required for this operation." }, { "enum": [ "BP-DR-209" ], "description": "Token not found for deletion." } ], "example": "BP-DR-49" }, "token-error-response": { "title": "Token Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when token creation fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "enum": [ "ERROR" ], "description": "Indicates the operation failed.\n", "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/token-error-code" }, { "$ref": "#/components/schemas/auth-error-code" }, { "$ref": "#/components/schemas/api-error-code" } ], "description": "The error code identifying what went wrong.\n", "example": "BP-DR-49" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Field creditcard.card_number is required" } } }, "set-cvv-request": { "title": "Set CVV Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for the setCVV operation.\n", "required": [ "token", "card_cvv" ], "properties": { "public_integration_key": { "type": "string", "description": "Your unique and public integration key. Use this instead of `integration_key` when the request comes from the client side.\n", "minLength": 1, "maxLength": 100, "example": "your_test_public_integration_key" }, "token": { "type": "string", "description": "The token to associate the CVV with.\n", "minLength": 32, "maxLength": 128, "example": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6" }, "card_cvv": { "type": "string", "description": "The Card Verification Value to associate with the token (3-4 digits).\n", "minLength": 3, "maxLength": 4, "example": "123" } } }, "set-cvv-success-response": { "title": "Set CVV Success Response", "x-schema-group": "Responses", "type": "object", "description": "Successful response when a CVV is associated with a token.\n", "required": [ "status", "token", "masked_card_number" ], "properties": { "status": { "type": "string", "enum": [ "SUCCESS" ], "description": "Indicates the operation was successful.\n", "example": "SUCCESS" }, "token": { "type": "string", "description": "The token that the CVV was associated with.\n", "minLength": 32, "maxLength": 128, "example": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6" }, "masked_card_number": { "type": "string", "description": "The masked credit card number associated with the token.\n", "minLength": 14, "maxLength": 19, "example": "411111xxxxxx1111" } } }, "set-cvv-error-response": { "title": "Set CVV Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the setCVV operation fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "enum": [ "ERROR" ], "description": "Indicates the operation failed.\n", "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/token-error-code" }, { "$ref": "#/components/schemas/auth-error-code" }, { "$ref": "#/components/schemas/api-error-code" } ], "description": "The error code identifying what went wrong.\n", "example": "BP-DR-64" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Token not found" } } }, "query-request-2": { "title": "Token Query Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for the token query operation.\n", "required": [ "token" ], "properties": { "public_integration_key": { "type": "string", "description": "Your unique and public integration key. Use this instead of `integration_key` when the request comes from the client side.\n", "minLength": 1, "maxLength": 100, "example": "your_test_public_integration_key" }, "token": { "type": "string", "description": "The token to query.\n", "minLength": 32, "maxLength": 128, "example": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6" } } }, "query-success-response": { "title": "Token Query Success Response", "x-schema-group": "Responses", "type": "object", "description": "Successful response when querying an existing card token.\n", "required": [ "card_type", "country", "due_date", "bin", "last_four" ], "properties": { "card_type": { "type": "string", "description": "The credit card brand/scheme associated with the token.\n", "example": "visa" }, "country": { "type": "string", "description": "The country associated with the token. Currently returns a fixed value.\n", "example": "not informed" }, "due_date": { "type": "string", "description": "The card expiration date stored with the token.\n", "example": "12/2028" }, "bin": { "type": "string", "description": "The first six digits (BIN) of the card number.\n", "minLength": 6, "maxLength": 6, "example": "411111" }, "last_four": { "type": "string", "description": "The last four digits of the card number.\n", "minLength": 4, "maxLength": 4, "example": "1111" }, "card_unique_id": { "type": "string", "description": "A unique identifier for the physical card, when available.\n", "example": "abc123def456" }, "network_token_status": { "description": "The provisioning status of a network token, when available.\n", "allOf": [ { "$ref": "#/components/schemas/network-token-status" } ], "example": "ACTIVE" }, "network_token_pan": { "type": "string", "x-conditional": "Not returned when authenticated with public_integration_key only", "description": "The network token PAN, when available.\n", "example": "4000000000001234" }, "network_token_cryptogram": { "type": "string", "x-conditional": "Not returned when authenticated with public_integration_key only", "description": "The network token cryptogram, when available.\n", "example": "AgAAAAAABk4DWZ4C28yUQAAAAAA=" }, "network_token_due_date": { "type": "string", "x-conditional": "Not returned when authenticated with public_integration_key only", "description": "The network token expiration date, when available.\n", "example": "12/2030" }, "network_token_credit_card_name": { "type": "string", "x-conditional": "Not returned when authenticated with public_integration_key only", "description": "The cardholder name associated with the network token, when available.\n", "example": "Jose da Silva" }, "payment_account_reference": { "type": "string", "description": "The Payment Account Reference (PAR) for the card, when available.\n", "example": "V0010013020217426736475648168" }, "threedsecure": { "type": "object", "title": "3D Secure", "description": "3D Secure authentication details associated with the token, when available.\n", "properties": { "status": { "description": "The 3D Secure authentication status.\n", "allOf": [ { "$ref": "#/components/schemas/threeds-authentication-status" } ], "example": "AUTHENTICATION_DONE" } } }, "card_verification": { "$ref": "#/components/schemas/card-verification" } } }, "query-error-response-2": { "title": "Token Query Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the token query operation fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "enum": [ "ERROR" ], "description": "Indicates the operation failed.\n", "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/token-error-code" }, { "$ref": "#/components/schemas/auth-error-code" }, { "$ref": "#/components/schemas/api-error-code" } ], "description": "The error code identifying what went wrong.\n", "example": "BP-DR-64" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Token not found" } } }, "delete-request": { "title": "Token Delete Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for the token delete operation.\n", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The token to delete.\n", "minLength": 32, "maxLength": 128, "example": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6" } } }, "delete-success-response": { "title": "Token Delete Success Response", "x-schema-group": "Responses", "type": "object", "description": "Response when the network token associated with the card token was successfully deleted.\n", "required": [ "status", "network_token_status" ], "properties": { "status": { "type": "string", "enum": [ "SUCCESS" ], "description": "Indicates the network token was successfully deleted.\n", "example": "SUCCESS" }, "network_token_status": { "description": "The network token status after the deletion attempt.\n", "allOf": [ { "$ref": "#/components/schemas/network-token-status" } ], "example": "DELETED" } } }, "delete-failed-response": { "title": "Token Delete Failed Response", "x-schema-group": "Responses", "type": "object", "description": "Response when the card token was found but the associated network token could not be deleted.\n", "required": [ "status", "network_token_status" ], "properties": { "status": { "type": "string", "enum": [ "FAILED" ], "description": "Indicates the network token deletion was not successful.\n", "example": "FAILED" }, "network_token_status": { "description": "The current status of the network token after the failed deletion attempt.\n", "allOf": [ { "$ref": "#/components/schemas/network-token-status" } ], "example": "ACTIVE" } } }, "delete-error-response": { "title": "Token Delete Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the token delete operation fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "enum": [ "ERROR" ], "description": "Indicates the operation failed.\n", "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/token-error-code" }, { "$ref": "#/components/schemas/auth-error-code" }, { "$ref": "#/components/schemas/api-error-code" } ], "description": "The error code identifying what went wrong.\n", "example": "BP-DR-209" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Token not found" } } }, "card-bin-request": { "x-hidden": true, "x-schema-group": "Requests", "title": "Card BIN Request", "type": "object", "properties": { "country": { "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code.\nIf sent, returns only the BINs for the specified country.\nWhen omitted, returns BINs for all supported countries.\n", "example": "BR" }, "bank_info": { "type": "boolean", "description": "If set to `true`, includes the issuer bank name in the `fullBankName` field of each BIN entry, when available.\nWhen omitted or `false`, the `fullBankName` field is not included.\n", "default": false, "example": true }, "blocked": { "type": "boolean", "description": "Filters the BIN list by blocked status.\nIf `true`, returns only blocked BINs. If `false`, returns only non-blocked BINs.\nWhen omitted, returns all BINs regardless of blocked status.\n", "example": false } } }, "card-bin-entry": { "x-hidden": true, "x-schema-group": "Responses", "title": "Card BIN Entry", "type": "object", "description": "A single card BIN entry containing the BIN code and associated card metadata.\n", "required": [ "bin", "cardBrand", "isoCountryA2", "cardType" ], "properties": { "bin": { "type": "string", "description": "The Bank Identification Number (first 6 digits of the card number).\n", "minLength": 6, "maxLength": 6, "example": "411111" }, "cardBrand": { "type": "string", "description": "The card brand or network name.\n", "example": "VISA" }, "isoCountryA2": { "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code indicating the card's country of origin.\n", "minLength": 2, "maxLength": 2, "example": "BR" }, "cardType": { "type": "string", "description": "The type of card associated with this BIN.\n", "enum": [ "COMBO", "CREDIT", "DEBIT", "JUNAEB", "PREPAGO", "PREPAID", "PRIVATE", "VOUCHER" ], "example": "CREDIT" }, "extension": { "type": "string", "description": "BIN extension digits. Only present for specific BINs that require additional digits for routing.\n", "example": "124" }, "fullBankName": { "type": "string", "nullable": true, "description": "The name of the issuing bank or financial institution.\nOnly included when `bank_info` is set to `true` in the request.\n", "example": "ITAU UNIBANCO S.A" } } }, "card-bin-success-response": { "x-schema-group": "Responses", "title": "Card BIN Success Response", "type": "object", "required": [ "numberOfBins", "binList" ], "properties": { "numberOfBins": { "type": "integer", "description": "The total number of BINs returned in the response.\n", "example": 3 }, "binList": { "type": "array", "description": "The list of card BIN entries matching the request filters.\n", "items": { "$ref": "#/components/schemas/card-bin-entry" } } } }, "card-bin-error-response": { "x-schema-group": "Responses", "title": "Card BIN Error Response", "type": "object", "description": "Error response returned when authentication or merchant validation fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the response.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code identifying what went wrong.\n", "example": "BP-SA-2" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Parameter integration_key not informed" } } }, "get-bank-list-request": { "title": "Get Bank List Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for the bank list query. Queries EBANX for available banks for a given country\nand optional payment type.\n", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "description": "The two-letter country code (ISO 3166-1 alpha-2, lowercase) indicating the country\nwhose bank list should be returned.\n", "minLength": 2, "maxLength": 2, "example": "co" }, "payment_type": { "type": "string", "description": "An optional payment type filter. When a bank list provider is available\nfor the payment type, the endpoint returns its list.\nIf no provider is available, or its list is unavailable or empty, the\nendpoint falls back to the country's general bank list. When the payment\ntype is omitted, the country's general bank list is returned.\nThe request returns `BP-DR-77` when the country is not enabled or the\nresulting bank list is empty.\n", "example": "eft" }, "device_os": { "type": "string", "description": "The operating system of the customer's device. Some payment types return a\ndifferent bank list per operating system. The value is case-insensitive.\nThe request returns `BP-DR-221` when the field is missing and `BP-DR-222`\nwhen the value is not accepted.\n", "x-conditional": "Required if payment_type is vietqr", "enum": [ "android", "ios" ], "example": "android" } } }, "bank-entity": { "title": "Bank List Item", "x-schema-group": "Responses", "x-hidden": true, "type": "object", "description": "A bank available for processing payments.\n", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "description": "The bank code. Used as the `eft_code` parameter in payment requests, or as\nthe `payment_type_code` for Brazil bank transfer methods.\n", "example": "banco_agrario" }, "name": { "type": "string", "description": "The display name of the bank.\n", "example": "BANCO AGRARIO" }, "logo_url": { "type": "string", "description": "The URL of the bank's logo image, when available.\n", "example": "https://cdn.ebanx.com/logos/banco_agrario.svg" } } }, "get-bank-list-success-response": { "title": "Get Bank List Success Response", "x-schema-group": "Responses", "type": "array", "description": "List of banks available for processing payments in the requested country.\n", "items": { "$ref": "#/components/schemas/bank-entity" } }, "get-bank-list-error-code": { "title": "Get Bank List Error Code", "x-schema-group": "Error Codes", "type": "string", "description": "Endpoint-specific error codes returned by `/ws/getBankList`.\n", "oneOf": [ { "enum": [ "BP-DR-77" ], "description": "Country is not enabled or no banks are available for the specified country and payment type." }, { "enum": [ "BP-DR-221" ], "description": "Field `device_os` is required for the specified payment type." }, { "enum": [ "BP-DR-222" ], "description": "Field `device_os` is invalid. Accepted values are `android` and `ios`." } ], "example": "BP-DR-77" }, "get-bank-list-error-response": { "title": "Get Bank List Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the bank list request fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "Indicates the request resulted in an error.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/get-bank-list-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code identifying what went wrong. Includes Get Bank List-specific\n(BP-DR-*) and Authentication (BP-SA-*) error codes.\n", "example": "BP-DR-77" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Country is not enabled" } } }, "instalments-plan-request": { "title": "Instalments Plan Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for the `/ws/instalmentsPlan` endpoint.\n", "required": [ "country_abbreviation", "currency_code", "amount" ], "properties": { "public_key": { "type": "string", "description": "Your EBANX public integration key.\n", "minLength": 1, "maxLength": 100, "example": "pk_your_test_public_key", "x-conditional": "Required when integration_key is not provided." }, "country_abbreviation": { "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code.\n", "minLength": 2, "maxLength": 2, "example": "BR" }, "currency_code": { "type": "string", "description": "Three-letter ISO 4217 currency code.\n", "minLength": 3, "maxLength": 3, "example": "BRL" }, "amount": { "type": "number", "description": "The total payment amount in the specified currency.\n", "minimum": 0, "exclusiveMinimum": true, "example": 100 }, "document": { "type": "string", "description": "Customer's document number (CPF).\n", "maxLength": 32, "example": "853.513.468-93", "x-conditional": "Required when using NuPay or NuPay Recurrent payment types." }, "payment_type": { "type": "string", "description": "The payment type code for the installments plan.\n", "example": "creditcard" }, "bin": { "type": "string", "description": "Credit card BIN (first 6 digits). When provided, the response includes card BIN information.\n", "example": "411111" }, "enrollment_code": { "type": "string", "description": "The enrollment code for the payment.\n", "example": "ENR-12345", "x-conditional": "Required when using NuPay or NuPay Recurrent payment types without a valid BIN." } }, "anyOf": [ { "required": [ "integration_key" ] }, { "required": [ "public_key" ] } ] }, "provider-instalment-detail": { "title": "Provider Instalment Detail", "x-schema-group": "Responses", "x-hidden": true, "type": "object", "description": "A single installment option from a provider-specific installments plan (e.g., NuPay).\n", "properties": { "totalAmount": { "type": "number", "description": "The original payment amount in the specified currency.\n", "example": 2000 }, "quantity": { "type": "integer", "description": "Number of installments.\n", "example": 1 }, "instalmentAmount": { "type": "number", "description": "Amount per installment.\n", "example": 2257.81 }, "instalmentAmountPercentage": { "type": "number", "nullable": true, "description": "Installment amount as a percentage of the total.\n", "example": 100 }, "interest": { "type": "number", "nullable": true, "description": "Interest rate applied to this installment option.\n", "example": 0.11 }, "interestAmount": { "type": "number", "nullable": true, "description": "Total interest amount in the local currency.\n", "example": 240.38 }, "iof": { "type": "number", "nullable": true, "description": "IOF (Tax on Financial Operations) amount.\n", "example": 17.43 }, "iofPercentage": { "type": "number", "nullable": true, "description": "IOF rate as a decimal fraction.\n", "example": 0.008 }, "totalAmountPercentage": { "type": "number", "nullable": true, "description": "Total amount as a percentage relative to the contracted amount.\n", "example": 1.11 }, "amountContracted": { "type": "number", "nullable": true, "description": "The contracted amount (principal plus IOF).\n", "example": 2017.43 }, "amountContractedPercentage": { "type": "number", "nullable": true, "description": "The contracted amount as a percentage.\n", "example": 1 }, "cet": { "type": "number", "nullable": true, "description": "Total Effective Cost (Custo Efetivo Total), the annualized cost of the credit operation.\n", "example": 1.06 }, "installmentPlanAdditionalLimit": { "type": "number", "nullable": true, "description": "The additional credit limit available for this installment plan.\n", "example": 2257.81 }, "additionalLimit": { "type": "number", "nullable": true, "description": "The total additional credit limit available.\n", "example": 5000 }, "additionalLimitMessage": { "type": "string", "nullable": true, "description": "A message describing the additional credit limit behavior.\n", "example": "Additional limit available" }, "totalAmountWithInterest": { "type": "number", "description": "Total amount including interest.\n", "example": 2257.81 } } }, "card-bin-info": { "title": "Card BIN Info", "x-schema-group": "Responses", "x-hidden": true, "type": "object", "description": "Card BIN (Bank Identification Number) information, when available.\n", "properties": { "bin": { "type": "string", "description": "The card BIN (first 6 digits).\n", "example": "411111" }, "brand": { "type": "string", "description": "The card brand.\n", "example": "VISA" }, "country": { "type": "string", "description": "The two-letter country code where the card was issued.\n", "example": "BR" } } }, "additional-info": { "title": "Additional Info", "x-schema-group": "Responses", "x-hidden": true, "type": "object", "description": "Additional information extracted from provider installment responses, when available.\n", "properties": { "credit_with_additional_limit": { "title": "Credit With Additional Limit Info", "type": "object", "description": "Additional limit information for the credit with additional limit modality.\n", "properties": { "additionalLimitMessage": { "type": "string", "description": "A message describing the additional credit limit behavior.\n", "example": "Additional limit available" } } } } }, "instalments-plan-success-response": { "title": "Instalments Plan Success Response", "x-schema-group": "Responses", "type": "object", "description": "Successful response containing the installments plan and optionally card BIN information.\n", "required": [ "instalmentsPlan" ], "properties": { "instalmentsPlan": { "oneOf": [ { "title": "Standard Instalments Plan", "type": "array", "description": "Array of installment options for standard payment types (e.g., credit card).\n", "items": { "title": "Instalment Detail", "type": "object", "description": "A single installment option in the standard installments plan.\n", "properties": { "totalAmount": { "type": "number", "description": "Total amount considering the indicated number of installments, including any applicable fees.\n", "example": 103.5 }, "quantity": { "type": "integer", "description": "Number of installments.\n", "example": 1 }, "instalmentAmount": { "type": "number", "description": "Amount per installment.\n", "example": 103.5 }, "appliedFee": { "type": "number", "description": "Fee percentage applied to this installment option, expressed as a decimal fraction (e.g., 0.01 represents 1%).\n", "example": 0.01 } } } }, { "title": "Provider Instalments Plan", "type": "object", "description": "Installment options grouped by modality for provider-specific payment types (e.g., NuPay).\n", "properties": { "credit": { "type": "array", "description": "Installment options for credit modality.\n", "items": { "$ref": "#/components/schemas/provider-instalment-detail" } }, "debit": { "type": "array", "description": "Installment options for debit modality.\n", "items": { "$ref": "#/components/schemas/provider-instalment-detail" } }, "credit_with_additional_limit": { "type": "array", "description": "Installment options for credit with additional limit modality.\n", "items": { "$ref": "#/components/schemas/provider-instalment-detail" } } } } ] }, "bin": { "$ref": "#/components/schemas/card-bin-info" }, "additionalInfo": { "$ref": "#/components/schemas/additional-info" } } }, "instalments-plan-error-code": { "title": "Instalments Plan Error Code", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to the `/ws/instalmentsPlan` endpoint.\n", "oneOf": [ { "enum": [ "BP-DR-23" ], "description": "Invalid document provided. The document must be a valid CPF." }, { "enum": [ "IPBP-001" ], "description": "Country abbreviation is required." }, { "enum": [ "IPBP-002" ], "description": "Amount is required." }, { "enum": [ "IPBP-003" ], "description": "Currency code is required." }, { "enum": [ "IPBP-004" ], "description": "Invalid country abbreviation." }, { "enum": [ "IPBP-005" ], "description": "Invalid currency code, or the currency rate is not available for the requested currency pair." }, { "enum": [ "IPBP-006" ], "description": "An unexpected error occurred while processing the request." }, { "enum": [ "IPBP-007" ], "description": "Invalid amount value. The amount must be a positive number greater than zero." }, { "enum": [ "IPBP-008" ], "description": "An external service required for installment calculation is not available." }, { "enum": [ "IPBP-SA-1" ], "description": "Either an integration_key or public_key parameter must be provided." }, { "enum": [ "IPBP-SA-2" ], "description": "Invalid public integration key." } ], "example": "IPBP-001" }, "instalments-plan-error-response": { "title": "Instalments Plan Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response from the `/ws/instalmentsPlan` endpoint.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "Indicates the request resulted in an error.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "description": "The error code identifying what went wrong.\n", "oneOf": [ { "$ref": "#/components/schemas/instalments-plan-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "example": "IPBP-001" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Country abbreviation is required" } } }, "enrollment-object-base": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Object Base", "description": "Common fields of the `enrollment` object shared across payment methods. `merchant_enrollment_code`\nis required in every operation that uses this object (create and cancel). Composes the shared\nreference and customer field fragments.\n", "required": [ "merchant_enrollment_code" ], "allOf": [ { "$ref": "#/components/schemas/enrollment-reference-fields" }, { "$ref": "#/components/schemas/enrollment-customer-fields" }, { "type": "object", "title": "Enrollment Object Base Extra Fields", "properties": { "intent_url": { "type": "string", "description": "Intent URL used by some redirect-based enrollment flows.", "example": "https://merchant.example.com/intent" } } } ] }, "enrollment-address-fields": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Address Fields", "description": "Customer address fields provided when creating an enrollment. They follow the same names and\nformats used by the customer address on the payment request (ws/direct). All of them are\noptional and are only forwarded to payment methods that require the customer address.\n", "properties": { "address": { "type": "string", "description": "Customer address (street name).\n", "minLength": 1, "maxLength": 100, "example": "Rua E" }, "street_number": { "type": "string", "description": "Customer street number.\n", "minLength": 1, "maxLength": 30, "example": "1040" }, "street_complement": { "type": "string", "description": "Customer address complement (apartment, suite, etc.).\n", "maxLength": 100, "example": "Apt 101" }, "city": { "type": "string", "description": "Customer city.\n", "minLength": 1, "maxLength": 80, "example": "Maracanau" }, "state": { "type": "string", "description": "Customer state/region/province.\n", "maxLength": 40, "example": "SP" }, "zipcode": { "type": "string", "description": "Customer's zipcode.\n", "maxLength": 20, "example": "61919-230" } } }, "create-enrollment-object-base": { "x-hidden": true, "x-schema-group": "Shared", "title": "Create Enrollment Object Base", "description": "Base for the `enrollment` object on the create operation. Extends the common enrollment object\nwith `country` as a required field — `country` is mandatory for every create enrollment payment\ntype — and with the optional customer address fields. The cancel operation references\n`enrollment-object-base.yaml` directly, since it does not require `country`.\n", "allOf": [ { "$ref": "#/components/schemas/enrollment-object-base" }, { "$ref": "#/components/schemas/enrollment-address-fields" }, { "type": "object", "title": "Create Enrollment Object Base Extra Fields", "required": [ "country" ] } ] }, "back-urls-2": { "x-hidden": true, "x-schema-group": "Shared", "title": "Enrollment Back URLs", "description": "URLs the customer is redirected to after completing or failing the enrollment flow.\nBoth URLs are required for ws/userenrollment.\n", "type": "object", "allOf": [ { "$ref": "#/components/schemas/back-urls" }, { "type": "object", "title": "Back Urls Extra Fields", "required": [ "success", "failure" ] } ] }, "mercado-pago-connect": { "x-schema-group": "Requests", "title": "Mercado Pago Connect Enrollment Request", "description": "Enrollment object for Mercado Pago Connect. Available in multiple countries.\n", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "Mercado Pago Connect Extra Fields", "properties": { "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2). Mercado Pago Connect is available in Argentina, Brazil, Chile, Mexico, and Uruguay.", "enum": [ "ar", "br", "cl", "mx", "uy" ], "example": "br" }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" } } } ] }, "enrollment": { "x-hidden": true, "title": "Argentina", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect" } ] }, "nupay-recurring": { "x-schema-group": "Requests", "title": "NuPay Recurring Enrollment Request", "description": "Enrollment object for Brazil NuPay recurring agreements.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "NuPay Recurring Extra Fields", "properties": { "country": { "enum": [ "br" ], "type": "string", "example": "br" }, "subscription": { "$ref": "#/components/schemas/subscription" }, "source": { "type": "string", "enum": [ "app", "web" ], "example": "app", "description": "NuPay authorization flow used to create the agreement.\n- `app`: App-to-App flow. The customer is redirected to the NuPay app through a deeplink.\n- `web`: Web-to-App flow. The customer receives a push notification in the NuPay app.\n\nWhen informed, the customer CPF is required.\nWhen omitted, the flow is selected by the customer CPF: Web-to-App when it is informed, App-to-App otherwise.\n" } } } ] }, "pix-automatico-3": { "x-schema-group": "Requests", "title": "Pix Automatico Enrollment Request", "description": "Enrollment object for Brazil Pix Automatico recurring agreements.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "Pix Automatico Extra Fields", "required": [ "back_urls" ], "properties": { "country": { "enum": [ "br" ], "type": "string", "example": "br" }, "name": { "type": "string", "description": "Customer's full name (Pix Automatico enforces 1 to 140 characters).", "minLength": 1, "maxLength": 140, "example": "John Doe" }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" }, "subscription": { "$ref": "#/components/schemas/subscription" } } } ] }, "enrollment-2": { "x-hidden": true, "title": "Brazil", "oneOf": [ { "$ref": "#/components/schemas/nupay-recurring" }, { "$ref": "#/components/schemas/pix-automatico-3" }, { "$ref": "#/components/schemas/mercado-pago-connect" } ] }, "enrollment-3": { "x-hidden": true, "title": "Chile", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect" } ] }, "nequi-recurring-3": { "x-schema-group": "Requests", "title": "Nequi Recurring Enrollment Request", "description": "Enrollment object for Colombia Nequi recurring agreements.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "Nequi Recurring Extra Fields", "properties": { "country": { "enum": [ "co" ], "type": "string", "example": "co" }, "subscription": { "$ref": "#/components/schemas/subscription" } } } ] }, "enrollment-4": { "x-hidden": true, "title": "Colombia", "oneOf": [ { "$ref": "#/components/schemas/nequi-recurring-3" } ] }, "card-enrollment-request": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Card", "description": "Card details for enrollment requests. A minimal card schema containing only the\nfields applicable to enrollment (a subset of the full card-request used by ws/direct).\n", "properties": { "card_number": { "type": "string", "description": "Card number.", "example": "4111111111111111" }, "card_name": { "type": "string", "description": "Name printed on the card.", "example": "John Doe" }, "card_due_date": { "type": "string", "description": "Card expiry date.", "pattern": "^(0[1-9]|1[0-2])/\\d{4}$", "example": "08/2027" }, "card_cvv": { "type": "string", "description": "Card security code.", "example": "123" }, "threeds_force": { "type": "boolean", "description": "Whether to force 3DS authentication.", "example": true } } }, "card-recurring": { "x-schema-group": "Requests", "title": "Card Recurring Enrollment Request", "description": "Enrollment object for India card (credit/debit) recurring subscriptions.\nCard data is sent under `card`.\n", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "Card Recurring Extra Fields", "required": [ "card" ], "properties": { "country": { "enum": [ "in" ], "type": "string", "example": "in" }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" }, "subscription": { "$ref": "#/components/schemas/subscription" }, "card": { "$ref": "#/components/schemas/card-enrollment-request" } } } ] }, "upi-autopay-3": { "x-schema-group": "Requests", "title": "UPI Autopay Enrollment Request", "description": "Enrollment object for India UPI Autopay recurring mandates\n(upi-collect-autopay, upi-qrcode-autopay, upi-intent-autopay).\n", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "UPI Autopay Extra Fields", "required": [ "upi" ], "properties": { "country": { "enum": [ "in" ], "type": "string", "example": "in" }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" }, "subscription": { "allOf": [ { "$ref": "#/components/schemas/subscription" }, { "required": [ "subscription_name", "frequency" ] } ] }, "upi": { "$ref": "#/components/schemas/upi" } } } ] }, "enrollment-5": { "x-hidden": true, "title": "India", "oneOf": [ { "$ref": "#/components/schemas/card-recurring" }, { "$ref": "#/components/schemas/upi-autopay-3" } ] }, "enrollment-6": { "x-hidden": true, "title": "Mexico", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect" } ] }, "direct-debit-3": { "x-schema-group": "Requests", "title": "Nigeria Direct Debit Enrollment Request", "description": "Enrollment object for Nigerian direct debit mandates through the provider selected by the\nmerchant's payment type profile. The mandate is created against the payer's bank account,\nso `account_details` and `subscription` (with `fixed_amount`, `max_amount_floor`, or both\n`min_amount` and `max_amount`, plus `frequency`, `start_date` and `expiration_date`) must be sent along with the customer's `name`,\n`phone_number`, `email` and `address`.\n", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "Nigeria Direct Debit Enrollment Fields", "required": [ "account_details", "address", "email", "name", "phone_number", "subscription" ], "properties": { "country": { "enum": [ "ng" ], "type": "string", "example": "ng" }, "account_details": { "$ref": "#/components/schemas/direct-debit-account-details" }, "address": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Payer's street address.", "example": "123 Broad Street" }, "email": { "type": "string", "format": "email", "description": "Payer's email address.", "example": "customer@example.com" }, "name": { "type": "string", "minLength": 1, "description": "Payer's full name.", "example": "John Doe" }, "phone_number": { "type": "string", "minLength": 1, "description": "Payer's phone number including the country code.", "example": "2348012345678" }, "subscription": { "allOf": [ { "$ref": "#/components/schemas/direct-debit-subscription" }, { "type": "object", "title": "Nigeria Direct Debit Enrollment Subscription Amount", "anyOf": [ { "type": "object", "title": "Nigeria Direct Debit Fixed Subscription Amount", "additionalProperties": true, "required": [ "fixed_amount" ], "properties": { "fixed_amount": { "type": "string", "nullable": false, "minLength": 1, "example": "100.00", "not": { "enum": [ "", "0" ] } } } }, { "type": "object", "title": "Nigeria Direct Debit Floored Subscription Amount", "additionalProperties": true, "required": [ "max_amount_floor" ], "properties": { "max_amount_floor": { "type": "string", "nullable": false, "minLength": 1, "example": "100.00", "not": { "enum": [ "", "0" ] } } } }, { "type": "object", "title": "Nigeria Direct Debit Variable Subscription Amount", "additionalProperties": true, "required": [ "min_amount", "max_amount" ], "properties": { "min_amount": { "type": "string", "minLength": 1, "example": "10.00", "not": { "enum": [ "", "0" ] } }, "max_amount": { "type": "string", "minLength": 1, "example": "100.00", "not": { "enum": [ "", "0" ] } } } } ] } ] } } } ] }, "enrollment-7": { "x-hidden": true, "title": "Nigeria", "oneOf": [ { "$ref": "#/components/schemas/direct-debit-3" } ] }, "yape-recurring-3": { "x-schema-group": "Requests", "title": "Yape Recurring Enrollment Request", "description": "Enrollment object for Peru Yape recurring agreements.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "Yape Recurring Extra Fields", "properties": { "country": { "enum": [ "pe" ], "type": "string", "example": "pe" }, "subscription": { "$ref": "#/components/schemas/subscription" }, "yape": { "type": "object", "title": "Yape", "description": "Yape-specific enrollment details. Either `yape` or `subscription` must be provided;\nwhen `yape` is present, both `type` and `source` are required.\n", "required": [ "source", "type" ], "properties": { "type": { "type": "string", "description": "Yape enrollment type.", "enum": [ "on_demand", "recurrent" ], "example": "recurrent" }, "source": { "type": "string", "description": "Yape enrollment source (the channel the customer enrolls from).", "enum": [ "mobile", "web" ], "example": "web" } } } } } ] }, "enrollment-8": { "x-hidden": true, "title": "Peru", "oneOf": [ { "$ref": "#/components/schemas/yape-recurring-3" } ] }, "enrollment-9": { "x-hidden": true, "title": "Uruguay", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect" } ] }, "capitec-pay-recurring": { "x-schema-group": "Requests", "title": "Capitec Pay Recurring Enrollment Request", "description": "Enrollment object for South Africa Capitec Pay recurring agreements.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/create-enrollment-object-base" }, { "type": "object", "title": "Capitec Pay Recurring Extra Fields", "properties": { "country": { "enum": [ "za" ], "type": "string", "example": "za" }, "subscription": { "$ref": "#/components/schemas/subscription" } } } ] }, "enrollment-10": { "x-hidden": true, "title": "South Africa", "oneOf": [ { "$ref": "#/components/schemas/capitec-pay-recurring" } ] }, "user-enrollment-request": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Create Enrollment Request", "description": "Request body for creating a new enrollment via the `ws/userenrollment` endpoint.\nThe structure of the `enrollment` object varies by country and payment method.\n", "required": [ "operation", "payment_type_code", "enrollment" ], "properties": { "operation": { "type": "string", "description": "The operation type. Must be `enrollment` to create an enrollment.", "enum": [ "enrollment" ], "example": "enrollment" }, "payment_type_code": { "type": "string", "description": "The payment method type code that determines the enrollment flow.", "example": "pix-automatico" }, "enrollment": { "description": "Enrollment details. Structure varies by country and payment method.", "oneOf": [ { "$ref": "#/components/schemas/enrollment" }, { "$ref": "#/components/schemas/enrollment-2" }, { "$ref": "#/components/schemas/enrollment-3" }, { "$ref": "#/components/schemas/enrollment-4" }, { "$ref": "#/components/schemas/enrollment-5" }, { "$ref": "#/components/schemas/enrollment-6" }, { "$ref": "#/components/schemas/enrollment-7" }, { "$ref": "#/components/schemas/enrollment-8" }, { "$ref": "#/components/schemas/enrollment-9" }, { "$ref": "#/components/schemas/enrollment-10" } ] } } }, "enrollment-response-base": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Response Base", "description": "Base properties shared across all enrollment response objects regardless of\ncountry or payment method.\n", "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant's unique enrollment code.", "example": "my-enrollment-code-123" }, "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2).", "minLength": 2, "maxLength": 2, "example": "br" }, "name": { "type": "string", "description": "Customer's full name.", "example": "John Doe" }, "email": { "type": "string", "description": "Customer's email address.", "example": "john.doe@example.com" }, "phone_number": { "type": "string", "description": "Customer's phone number.", "example": "5555555555" }, "notification_url": { "type": "string", "description": "URL EBANX calls to notify enrollment status changes.", "example": "https://merchant.example.com/notify" }, "open_date": { "type": "string", "description": "Date and time when the enrollment was created (YYYY-MM-DD HH:MM:SS).", "example": "2024-12-01 12:00:00" }, "identification": { "type": "string", "description": "Customer's identification value, echoed when the enrollment was created using\n`identification`/`identification_type` instead of `document`.\n", "example": "853.513.468-93" }, "identification_type": { "type": "string", "description": "Type of the customer's identification (echoed alongside `identification`).\n", "example": "cpf" } } }, "mercado-pago-connect-2": { "x-schema-group": "Responses", "title": "Mercado Pago Connect Enrollment Response", "description": "Enrollment response object for Mercado Pago Connect.", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" } ] }, "enrollment-11": { "x-hidden": true, "title": "Argentina", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect-2" } ] }, "nupay-recurring-2": { "x-schema-group": "Responses", "title": "NuPay Recurring Enrollment Response", "description": "Enrollment response object for Brazil NuPay recurring.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "NuPay Recurring Extra Fields", "properties": { "subscription": { "$ref": "#/components/schemas/subscription-response" } } } ] }, "pix-automatico-4": { "x-schema-group": "Responses", "title": "Pix Automatico Enrollment Response", "description": "Enrollment response object for Brazil Pix Automatico.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "Pix Automatico Extra Fields", "properties": { "document": { "type": "string", "description": "Customer's document number (CPF).", "example": "853.513.468-93" }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" }, "subscription": { "$ref": "#/components/schemas/subscription-response" }, "status": { "type": "string", "description": "Current enrollment status.", "example": "pending" } } } ] }, "enrollment-12": { "x-hidden": true, "title": "Brazil", "oneOf": [ { "$ref": "#/components/schemas/nupay-recurring-2" }, { "$ref": "#/components/schemas/pix-automatico-4" }, { "$ref": "#/components/schemas/mercado-pago-connect-2" } ] }, "enrollment-13": { "x-hidden": true, "title": "Chile", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect-2" } ] }, "nequi-recurring-4": { "x-schema-group": "Responses", "title": "Nequi Recurring Enrollment Response", "description": "Enrollment response object for Colombia Nequi Recurring.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "Nequi Recurring Extra Fields", "properties": { "subscription": { "$ref": "#/components/schemas/subscription-response" } } } ] }, "enrollment-14": { "x-hidden": true, "title": "Colombia", "oneOf": [ { "$ref": "#/components/schemas/nequi-recurring-4" } ] }, "card-recurring-2": { "x-schema-group": "Responses", "title": "Card Recurring Enrollment Response", "description": "Enrollment response object for India Card Recurring.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "Card Recurring Extra Fields", "properties": { "document": { "type": "string", "description": "Customer's document number.", "example": "853.513.468-93" }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" }, "subscription": { "$ref": "#/components/schemas/subscription-response" } } } ] }, "upi-autopay-4": { "x-schema-group": "Responses", "title": "UPI Autopay Enrollment Response", "description": "Enrollment response object for India UPI Autopay.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "UPI Autopay Extra Fields", "properties": { "subscription": { "$ref": "#/components/schemas/subscription-response" }, "upi": { "type": "object", "title": "UPI", "description": "UPI details for the enrollment.", "properties": { "vpa": { "type": "string", "description": "Customer's UPI Virtual Payment Address.", "example": "customer@upi" }, "app_links": { "type": "object", "title": "App Links", "nullable": true, "description": "Deep links to UPI apps (e.g. gpay, phonepe, paytm, other_apps) for UPI Intent autopay.\n", "properties": { "gpay": { "type": "string", "example": "gpay://pay?..." }, "phonepe": { "type": "string", "example": "ppe://pay?..." }, "paytm": { "type": "string", "example": "paytmmp://pay?..." }, "other_apps": { "type": "string", "example": "upi://pay?..." } } } } }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" } } } ] }, "enrollment-15": { "x-hidden": true, "title": "India", "oneOf": [ { "$ref": "#/components/schemas/card-recurring-2" }, { "$ref": "#/components/schemas/upi-autopay-4" } ] }, "enrollment-16": { "x-hidden": true, "title": "Mexico", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect-2" } ] }, "direct-debit-4": { "x-schema-group": "Responses", "title": "Nigeria Direct Debit Enrollment Response", "description": "Enrollment response object for Nigerian direct debit one-time and recurring mandates.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "Nigeria Direct Debit Enrollment Fields", "properties": { "subscription": { "$ref": "#/components/schemas/subscription-response" } } } ] }, "enrollment-17": { "x-hidden": true, "title": "Nigeria", "oneOf": [ { "$ref": "#/components/schemas/direct-debit-4" } ] }, "yape-recurring-4": { "x-schema-group": "Responses", "title": "Yape Recurring Enrollment Response", "description": "Enrollment response object for Peru Yape Recurring.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "Yape Recurring Extra Fields", "properties": { "subscription": { "$ref": "#/components/schemas/subscription-response" } } } ] }, "enrollment-18": { "x-hidden": true, "title": "Peru", "oneOf": [ { "$ref": "#/components/schemas/yape-recurring-4" } ] }, "enrollment-19": { "x-hidden": true, "title": "Uruguay", "oneOf": [ { "$ref": "#/components/schemas/mercado-pago-connect-2" } ] }, "capitec-pay-recurring-2": { "x-schema-group": "Responses", "title": "Capitec Pay Recurring Enrollment Response", "description": "Enrollment response object for South Africa Capitec Pay Recurring.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-base" }, { "type": "object", "title": "Capitec Pay Recurring Extra Fields", "properties": { "subscription": { "$ref": "#/components/schemas/subscription-response" } } } ] }, "enrollment-20": { "x-hidden": true, "title": "South Africa", "oneOf": [ { "$ref": "#/components/schemas/capitec-pay-recurring-2" } ] }, "user-enrollment-response": { "x-schema-group": "Responses", "type": "object", "title": "Create Enrollment Response", "description": "Successful response for the enrollment create operation. The `enrollment` object\nstructure varies by country and payment method.\n", "properties": { "status": { "type": "string", "description": "The status of the request.", "enum": [ "SUCCESS" ], "example": "SUCCESS" }, "redirect_url": { "type": "string", "description": "The URL to redirect the customer to complete the enrollment. May be `no-redirect` for\nflows that do not require customer redirection.\n", "example": "https://checkout.example.com/enrollment/abc123" }, "enrollment": { "description": "The enrollment object. Structure varies by country and payment method.", "oneOf": [ { "$ref": "#/components/schemas/enrollment-11" }, { "$ref": "#/components/schemas/enrollment-12" }, { "$ref": "#/components/schemas/enrollment-13" }, { "$ref": "#/components/schemas/enrollment-14" }, { "$ref": "#/components/schemas/enrollment-15" }, { "$ref": "#/components/schemas/enrollment-16" }, { "$ref": "#/components/schemas/enrollment-17" }, { "$ref": "#/components/schemas/enrollment-18" }, { "$ref": "#/components/schemas/enrollment-19" }, { "$ref": "#/components/schemas/enrollment-20" } ] } } }, "user-enrollment-error-code": { "title": "User Enrollment Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to the User Enrollment API endpoint (`ws/userenrollment`).\nThese errors are returned in the `status_code` field of the error response.\n", "oneOf": [ { "enum": [ "BP-UE-01" ], "description": "Field operation is required." }, { "enum": [ "BP-UE-02" ], "description": "Invalid operation." }, { "enum": [ "BP-UE-03" ], "description": "A required enrollment field was not informed (e.g. enrollment.country or enrollment.merchant_enrollment_code)." }, { "enum": [ "BP-UE-04" ], "description": "A required enrollment field was sent empty." }, { "enum": [ "BP-UE-05" ], "description": "The URL provided for a back_urls field is invalid." }, { "enum": [ "BP-UE-06" ], "description": "Field enrollment.country must be a valid country abbreviation." }, { "enum": [ "BP-UE-07" ], "description": "Field payment_type_code is required." }, { "enum": [ "BP-UE-08" ], "description": "Field payment_type_code must be valid." }, { "enum": [ "BP-UE-09" ], "description": "The given payment_type_code is not enabled for this country." }, { "enum": [ "BP-UE-10" ], "description": "Payment type not enabled in full mode for the merchant." }, { "enum": [ "BP-UE-11" ], "description": "No provider enabled to process this operation." }, { "enum": [ "BP-UE-12" ], "description": "Unexpected error." }, { "enum": [ "BP-UE-13" ], "description": "Payment type profile not found or not supported for this operation." }, { "enum": [ "BP-UE-14" ], "description": "Enrollment not found." }, { "enum": [ "BP-UE-15" ], "description": "Provider-specific cancellation error." }, { "enum": [ "BP-UE-16" ], "description": "This enrollment code already exists, please generate another enrollment code for the customer." }, { "enum": [ "BP-UE-17" ], "description": "Authentication failed or subscription amount validation error." }, { "enum": [ "BP-UE-18" ], "description": "Field enrollment.subscription.expiration_date is invalid." }, { "enum": [ "BP-UE-19" ], "description": "Field enrollment.upi.vpa is mandatory or has an invalid format." }, { "enum": [ "BP-UE-20" ], "description": "At least one updatable field is required." }, { "enum": [ "BP-UE-21" ], "description": "A provided enrollment.subscription field is not updatable." }, { "enum": [ "BP-UE-22" ], "description": "Field enrollment must be present in the request." }, { "enum": [ "BP-UE-23" ], "description": "Field enrollment.subscription.frequency is required." }, { "enum": [ "BP-UE-24" ], "description": "Field enrollment.subscription.start_date is invalid." }, { "enum": [ "BP-UE-25" ], "description": "Field enrollment.subscription.recurrence_value must be an integer value." }, { "enum": [ "BP-UE-26" ], "description": "Field enrollment.subscription.retry must be a valid retry value." }, { "enum": [ "BP-UE-27" ], "description": "Field enrollment.subscription.subscription_name is required." }, { "enum": [ "BP-UE-28" ], "description": "Field enrollment.subscription.max_amount_floor is invalid." }, { "enum": [ "BP-UE-29" ], "description": "Field enrollment.subscription.fixed_amount is required." }, { "enum": [ "BP-UE-30" ], "description": "Field enrollment.name has an invalid size or format." }, { "enum": [ "BP-UE-31" ], "description": "Fields enrollment.yape.type and enrollment.yape.source are required for yape payments." }, { "enum": [ "BP-UE-32" ], "description": "Provider internal error." }, { "enum": [ "BP-UE-33" ], "description": "Timeout from provider." }, { "enum": [ "BP-UE-34" ], "description": "Invalid params from provider." }, { "enum": [ "BP-UE-35" ], "description": "Document status validation error." }, { "enum": [ "BP-UE-36" ], "description": "Subscription amount conflict error." }, { "enum": [ "BP-UE-37" ], "description": "Document name validation error." }, { "enum": [ "BP-UE-38" ], "description": "Authentication data is required." }, { "enum": [ "BP-UE-39" ], "description": "Authentication type not allowed for this operation." }, { "enum": [ "BP-UE-40" ], "description": "Parameter contract is required." }, { "enum": [ "BP-UE-41" ], "description": "Invalid contract." }, { "enum": [ "BP-UE-42" ], "description": "Provider rejected the enrollment." }, { "enum": [ "BP-UE-44" ], "description": "Origin header is required." }, { "enum": [ "BP-UE-45" ], "description": "Invalid origin host." }, { "enum": [ "BP-UE-46" ], "description": "Incorrect customer data from provider." }, { "enum": [ "BP-UE-48" ], "description": "Field enrollment.identification must be a valid CPF." }, { "enum": [ "BP-UE-49" ], "description": "Field enrollment.account_details.bank_id must be a supported bank." }, { "enum": [ "BP-UE-50" ], "description": "Field enrollment.subscription.start_date cannot be updated for enrollments with existing payments." }, { "enum": [ "BP-UE-51" ], "description": "Transaction limit exceeded from provider." }, { "enum": [ "BP-UE-52" ], "description": "Payment not valid from provider." }, { "enum": [ "BP-UE-53" ], "description": "Invalid amount from provider." }, { "enum": [ "BP-UE-54" ], "description": "Parameter enrollment.note can have 200 bytes maximum." } ], "example": "BP-UE-02" }, "user-enrollment-error-response": { "x-schema-group": "Responses", "title": "User Enrollment Error Response", "description": "Error response returned when a user enrollment request fails (validation, provider, or\nauthentication error).\n", "type": "object", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/user-enrollment-error-code" }, { "$ref": "#/components/schemas/auth-error-code" }, { "$ref": "#/components/schemas/api-error-code" } ], "description": "The error code identifying what went wrong. Includes User Enrollment (`BP-UE-*`),\nAuthentication (`BP-SA-*`) and general API/parser (`DA-*`, `BP-DPAR-*`) error codes.\n", "example": "BP-UE-02" }, "status_message": { "type": "string", "description": "A human-readable error message describing what went wrong.\n", "example": "Invalid operation" } } }, "cancel-request-2": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Cancel Enrollment Request", "description": "Request for the `cancel` operation. Cancels an existing enrollment identified by its\nmerchant_enrollment_code.\n", "required": [ "operation", "enrollment" ], "properties": { "operation": { "type": "string", "description": "The operation type. Must be `cancel`.", "enum": [ "cancel" ], "example": "cancel" }, "payment_type_code": { "type": "string", "description": "The payment method type code. Optional; when omitted the provider is resolved from the\nenrollment's payment type profile.\n", "example": "pix-automatico" }, "enrollment": { "type": "object", "title": "Cancel Enrollment", "additionalProperties": true, "description": "The enrollment to cancel. Only `merchant_enrollment_code` is used to locate the enrollment;\nany other fields are accepted but ignored.\n", "required": [ "merchant_enrollment_code" ], "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant's unique enrollment code identifying the enrollment to cancel.", "example": "my-enrollment-code-123" } } } } }, "enrollment-response-object": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Enrollment Response Object", "description": "The `enrollment` object returned by the enrollment operations. Fields vary by payment method\nand operation. Composes the shared enrollment status fields.\n", "allOf": [ { "$ref": "#/components/schemas/enrollment-status-response" }, { "type": "object", "title": "Enrollment Response Object Extra Fields", "properties": { "spi_code": { "type": "string", "description": "SPI recurrence reference code (Pix Automatico only, when available from the provider).", "example": "E12345678202412151030abcdef123456" }, "enrollment_provider_token": { "type": "string", "description": "Provider-assigned token for the enrollment (Nequi/Yape only, returned when the merchant\nconfig `return_enrollment_provider_token` is enabled).\n", "example": "tok_abc123def456" }, "document": { "type": "string", "description": "Customer's document number.", "example": "853.513.468-93" }, "notification_url": { "type": "string", "description": "URL EBANX calls to notify enrollment status changes.", "example": "https://merchant.example.com/notify" }, "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2).", "minLength": 2, "maxLength": 2, "example": "br" }, "name": { "type": "string", "description": "Customer's full name.", "example": "John Doe" }, "email": { "type": "string", "description": "Customer's email address.", "example": "john.doe@example.com" }, "phone_number": { "type": "string", "description": "Customer's phone number.", "example": "5555555555" }, "identification": { "type": "string", "description": "Customer's identification number.", "example": "12345678901" }, "identification_type": { "type": "string", "description": "Type of the identification (e.g. cpf).", "example": "cpf" }, "back_urls": { "$ref": "#/components/schemas/back-urls-2" }, "subscription": { "$ref": "#/components/schemas/subscription-response" }, "upi": { "type": "object", "title": "UPI", "description": "UPI details for India UPI Autopay enrollment.", "properties": { "vpa": { "type": "string", "description": "Customer's UPI Virtual Payment Address.", "example": "customer@upi" }, "app_links": { "type": "object", "title": "App Links", "nullable": true, "description": "Deep links to UPI apps for UPI Intent autopay. Keys represent app identifiers.\n", "properties": { "gpay": { "type": "string", "description": "Google Pay deep link.", "example": "gpay://pay?..." }, "phonepe": { "type": "string", "description": "PhonePe deep link.", "example": "ppe://pay?..." }, "paytm": { "type": "string", "description": "Paytm deep link.", "example": "paytmmp://pay?..." }, "other_apps": { "type": "string", "description": "Generic UPI intent link for other apps.", "example": "upi://pay?..." } } } } }, "open_date": { "type": "string", "description": "Date and time when the enrollment was created (YYYY-MM-DD HH:MM:SS).", "example": "2024-12-01 12:00:00" } } } ] }, "cancel-enrollment-response": { "x-schema-group": "Responses", "type": "object", "title": "Cancel Enrollment Response", "description": "Successful response for the cancel operation. The enrollment status is set to `revoked`.\nAdditional fields are returned depending on the payment type.\n", "properties": { "status": { "type": "string", "description": "The status of the request.", "enum": [ "SUCCESS" ], "example": "SUCCESS" }, "enrollment": { "title": "Cancelled Enrollment", "description": "The cancelled enrollment (status set to `revoked`). Fields vary by payment method and provider,\nas the object is enriched by the enrollment response morphers (the same used by the query\noperation).\n", "allOf": [ { "$ref": "#/components/schemas/enrollment-response-object" } ] }, "subscription": { "$ref": "#/components/schemas/subscription-response" }, "customer": { "type": "object", "title": "Customer Details", "description": "Customer details (Pix Automatico only).", "properties": { "email": { "type": "string", "description": "Customer's email address.", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "Customer's full name.", "example": "John Doe" }, "document": { "type": "string", "description": "Customer's document number (CPF).", "example": "853.513.468-93" }, "fingerprint": { "type": "string", "description": "Customer's device fingerprint.", "example": "fp_abc123" } } }, "payer": { "type": "object", "title": "Payer Bank Details", "description": "Payer bank details (Pix Automatico only).", "properties": { "bank_name": { "type": "string", "description": "Name of the payer's bank.", "example": "Banco do Brasil" }, "bank_ispb": { "type": "string", "description": "ISPB code of the payer's bank.", "example": "00000000" }, "agency_number": { "type": "string", "description": "Payer's bank agency number.", "example": "0001" }, "account_number": { "type": "string", "description": "Payer's bank account number.", "example": "12345-6" }, "document": { "type": "string", "description": "Payer's document number (CPF/CNPJ).", "example": "853.513.468-93" }, "fingerprint": { "type": "string", "description": "Payer's device fingerprint.", "example": "fp_xyz789" } } } } }, "update-enrollment-object": { "x-hidden": true, "x-schema-group": "Shared", "type": "object", "title": "Update Subscription Enrollment", "description": "The `enrollment` object for the `update_subscription` operation. The success response echoes it\nback exactly as provided in the request, so the same fields apply to both request and response.\n", "required": [ "merchant_enrollment_code" ], "properties": { "merchant_enrollment_code": { "type": "string", "description": "Merchant's unique enrollment code of the enrollment to update.", "example": "my-enrollment-code-123" }, "email": { "type": "string", "description": "Customer's email address.", "example": "john.doe@example.com" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter country code (ISO 3166-1 alpha-2).", "example": "in" }, "subscription": { "type": "object", "title": "Subscription Fields", "description": "The subscription fields to update (at least one is required).", "properties": { "min_amount": { "type": "string", "description": "New minimum amount allowed per charge.", "example": "10" }, "max_amount": { "type": "string", "description": "New maximum amount allowed per charge.", "example": "1000" }, "expiration_date": { "type": "string", "description": "New expiration date of the subscription.", "format": "date", "example": "2025-12-30" }, "fixed_amount": { "type": "string", "description": "New fixed amount charged on each cycle.", "example": "50" } } } } }, "update-subscription-request": { "x-hidden": true, "x-schema-group": "Requests", "type": "object", "title": "Update Subscription Request", "description": "Request for the `update_subscription` operation. Updates the mutable fields of an existing\nenrollment's subscription. Only `min_amount`, `max_amount`, `expiration_date` and\n`fixed_amount` are updatable, and at least one of them must be provided.\n", "required": [ "operation", "enrollment" ], "properties": { "operation": { "type": "string", "description": "The operation type. Must be `update_subscription`.", "enum": [ "update_subscription" ], "example": "update_subscription" }, "payment_type_code": { "type": "string", "description": "The payment method type code of the enrollment.", "example": "upi-collect-autopay" }, "enrollment": { "$ref": "#/components/schemas/update-enrollment-object" } } }, "update-subscription-response": { "x-hidden": true, "x-schema-group": "Responses", "type": "object", "title": "Update Subscription Response", "description": "Successful response for the `update_subscription` operation, echoing the updated enrollment.\n", "properties": { "status": { "type": "string", "description": "The status of the request.", "enum": [ "SUCCESS" ], "example": "SUCCESS" }, "enrollment": { "$ref": "#/components/schemas/update-enrollment-object" } } }, "update-subscription-error-code": { "title": "Update Subscription Error Codes", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes returned by the `update_subscription` operation's provider/subscription layer.\nThese are returned in the `status_code` field of the update-subscription error response.\n", "oneOf": [ { "enum": [ "BP-US-01" ], "description": "Error on update subscription." }, { "enum": [ "BP-US-03" ], "description": "External provider not found." }, { "enum": [ "BP-US-04" ], "description": "Invalid external provider." }, { "enum": [ "BP-US-05" ], "description": "Failed to update subscription on provider." }, { "enum": [ "BP-US-06" ], "description": "Subscription or enrollment not found for the given merchant_enrollment_code." } ], "example": "BP-US-05" }, "update-subscription-error-response": { "x-schema-group": "Responses", "title": "Update Subscription Error Response", "description": "Error response returned by the `update_subscription` operation when the provider/subscription\nlayer fails. This envelope uses `message` (instead of `status_message`) and may carry\nsubscription-specific (`BP-US-*`) or user-enrollment (`BP-UE-*`) error codes.\n", "type": "object", "required": [ "status", "status_code", "message" ], "properties": { "status": { "type": "string", "description": "The status of the request. Always `ERROR` for error responses.", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/update-subscription-error-code" }, { "$ref": "#/components/schemas/user-enrollment-error-code" } ], "description": "The error code. Includes Update Subscription (`BP-US-*`) and User Enrollment (`BP-UE-*`)\nerror codes.\n", "example": "BP-US-05" }, "message": { "type": "string", "description": "A human-readable error message describing what went wrong.", "example": "Failed to update subscription on provider" } } }, "document-balance-error-code": { "title": "Document Balance Error Code", "x-schema-group": "Error Codes", "type": "string", "description": "Error codes specific to the `/ws/documentbalance` endpoint.\n", "oneOf": [ { "enum": [ "BP-DOC-01" ], "description": "The provided document is invalid (not a valid CPF or CNPJ)." }, { "enum": [ "BP-DOC-02" ], "description": "The provided currency code is not supported." }, { "enum": [ "BP-DOC-03" ], "description": "The provided country code is not supported." }, { "enum": [ "BP-DOC-04" ], "description": "Currency conversion to the requested currency is not available." } ], "example": "BP-DOC-01" }, "document-balance-error-response": { "title": "Document Balance Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the request fails validation or authentication.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "Indicates the request resulted in an error.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/document-balance-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code identifying what went wrong. Includes Document Balance-specific (BP-DOC-*) and Authentication (BP-SA-*) error codes.\n", "example": "BP-DOC-01" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Invalid document: 1234567890" } } }, "document-balance-success-response": { "title": "Document Balance Success Response", "x-schema-group": "Responses", "type": "object", "description": "Successful response containing the customer's balance information for the current month.\n", "required": [ "status", "document_balance" ], "properties": { "status": { "type": "string", "description": "Indicates the request was processed successfully.\n", "enum": [ "SUCCESS" ], "example": "SUCCESS" }, "document_balance": { "title": "Document Balance", "x-schema-group": "Responses", "type": "object", "description": "The customer's balance details for the current month.\n", "required": [ "document", "balance", "available", "currency_code" ], "properties": { "document": { "type": "string", "description": "The customer's document number. For Brazil, CPF is returned formatted\nas `XXX.XXX.XXX-XX` and CNPJ as `XX.XXX.XXX/XXXX-XX`.\nFor other countries, the raw document number is returned.\n", "example": "853.513.468-93" }, "balance": { "type": "number", "description": "The amount already spent by the customer in the current month,\nconverted to the requested currency.\n", "example": 2000 }, "available": { "type": "number", "description": "The amount the customer can still spend in the current month,\nconverted to the requested currency.\n", "example": 1000 }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The currency code (ISO 4217) of the returned balance values.\n", "example": "USD" } } } } }, "document-balance-response": { "title": "Document Balance Response", "x-schema-group": "Responses", "oneOf": [ { "$ref": "#/components/schemas/document-balance-success-response" }, { "$ref": "#/components/schemas/document-balance-error-response" } ], "discriminator": { "propertyName": "status", "mapping": { "ERROR": "#/components/schemas/document-balance-error-response", "SUCCESS": "#/components/schemas/document-balance-success-response" } } }, "zip-code-request": { "title": "Zip Code Request", "x-schema-group": "Requests", "type": "object", "description": "Request body for the `/ws/zipcode` endpoint.\n", "required": [ "zipcode" ], "properties": { "zipcode": { "type": "string", "description": "A Brazilian zip code (CEP). Dashes and dots are automatically removed before validation. Must contain exactly 8 digits after sanitization.\n", "minLength": 8, "maxLength": 10, "pattern": "^[\\d.\\-]{8,10}$", "example": "61919-230" } } }, "zip-code-error-code": { "title": "Zip Code Error Code", "x-schema-group": "Enums", "type": "string", "description": "Error codes specific to the `/ws/zipcode` endpoint.\n", "oneOf": [ { "enum": [ "BP-ZIP-1" ], "description": "The zip code was not provided in the request." }, { "enum": [ "BP-ZIP-2" ], "description": "The zip code format is invalid. Must contain exactly 8 digits." }, { "enum": [ "BP-ZIP-3" ], "description": "The address could not be retrieved for the given zip code." } ], "example": "BP-ZIP-2" }, "zip-code-error-response": { "title": "Zip Code Error Response", "x-schema-group": "Responses", "type": "object", "description": "Error response returned when the zip code lookup fails.\n", "required": [ "status", "status_code", "status_message" ], "properties": { "status": { "type": "string", "description": "The status of the API request.\n", "enum": [ "ERROR" ], "example": "ERROR" }, "status_code": { "oneOf": [ { "$ref": "#/components/schemas/zip-code-error-code" }, { "$ref": "#/components/schemas/auth-error-code" } ], "description": "The error code. Can be a zip-code-specific code (BP-ZIP-*) or an authentication code (BP-SA-*).\n", "example": "BP-ZIP-2" }, "status_message": { "type": "string", "description": "A human-readable message describing the error.\n", "example": "Zipcode is not valid" } } }, "zip-code-success-response": { "title": "Zip Code Success Response", "x-schema-group": "Responses", "type": "object", "description": "Successful response containing the address information for the requested zip code.\n", "required": [ "status", "zipcode" ], "properties": { "status": { "type": "string", "description": "The status of the API request.\n", "enum": [ "SUCCESS" ], "example": "SUCCESS" }, "zipcode": { "title": "Zip Code Address", "x-schema-group": "Responses", "type": "object", "description": "Address information associated with the queried Brazilian zip code.\n", "required": [ "state", "city", "address" ], "properties": { "state": { "type": "string", "description": "The Brazilian state abbreviation (two-letter code).\n", "minLength": 2, "maxLength": 2, "example": "CE" }, "city": { "type": "string", "description": "The city name.\n", "minLength": 1, "maxLength": 128, "example": "Maracanaú" }, "address": { "type": "string", "description": "The street name. When available, contains the full street address for the zip code.\n", "maxLength": 256, "example": "Rua E" } } } } }, "zip-code-response": { "title": "Zip Code Response", "x-schema-group": "Responses", "oneOf": [ { "$ref": "#/components/schemas/zip-code-success-response" }, { "$ref": "#/components/schemas/zip-code-error-response" } ], "discriminator": { "propertyName": "status", "mapping": { "ERROR": "#/components/schemas/zip-code-error-response", "SUCCESS": "#/components/schemas/zip-code-success-response" } } } } }, "x-tagGroups": [ { "name": "Before a Pay-in", "tags": [ "FX", "Tokenization", "Enrollment", "Merchant Tools" ] }, { "name": "Create a Pay-in", "tags": [ "Direct Payments", "Payment Page" ] }, { "name": "After a Pay-in", "tags": [ "Cancel", "Refund", "Refund or Cancel", "Query" ] } ] }