Payment Methods

Adding a payment method to your Ecart Pay account lets you receive withdrawals. You can register a Mexican CLABE, a debit card, or another supported bank rail (for example ACH or SEPA, depending on your country).

This guide covers your payout destinations: POST/GET/PUT/DELETE /api/payment-methods. Saved cards for charging customers are a different resource (/api/customers/{customer_id}/cards).

To follow the steps below you need an Authorization token.

Scopes

• write_otp — send the verification code used on create, update, delete, and validate
• write_payment_methods — create, update, validate, request verification, delete
• read_payment_methods — list and retrieve (write also allows read)

You can keep up to 5 payment methods on your account.

Flow

1. List supported banks and their codes (GET /api/banks). Use clave as bank when you create the payment method.
2. Send a one-time code to your email or phone (POST /api/otp/send).
3. Create the payment method (POST /api/payment-methods) and include that code in otp.
4. For Mexican CLABE accounts, confirm ownership with your RFC (PATCH /api/payment-methods/validate). Validation is asynchronous.
5. Listen for payment_method.validation_approved or payment_method.validation_rejected.
6. Use the payment method id when you request a withdrawal.

Key parameters

List banks

GET https://sandbox.ecartpay.com/api/banks

Requires an authorization token. Use this list to populate a dropdown and to set bank when you create a payment method.

curl --location 'https://sandbox.ecartpay.com/api/banks?country=MX' \
  --header 'Authorization: YOUR_TOKEN'

Each item includes the bank name and its numeric code (clave):

[
  {
    "id": "5f331fb9f7480d71f16b91c9",
    "name": "BANAMEX",
    "clave": "40002",
    "country": "MX"
  },
  {
    "id": "5f331fb9f7480d71f16b91ca",
    "name": "BBVA BANCOMER",
    "clave": "40012",
    "country": "MX"
  },
  {
    "id": "5f331fb9f7480d71f16b91d6",
    "name": "BANORTE/IXE",
    "clave": "40072",
    "country": "MX"
  }
]

Send clave as bank on create. For Mexico, 40072 (Banorte) matches a CLABE that starts with 072.

Get one bank

GET https://sandbox.ecartpay.com/api/banks/{id}

curl --location 'https://sandbox.ecartpay.com/api/banks/5f331fb9f7480d71f16b91d6' \
  --header 'Authorization: YOUR_TOKEN'

{
  "id": "5f331fb9f7480d71f16b91d6",
  "name": "BANORTE/IXE",
  "clave": "40072",
  "country": "MX"
}

If the id does not exist, the API returns 404 (The bank does not exist.).

Send a verification code

POST https://sandbox.ecartpay.com/api/otp/send

Scope: write_otp

{
  "type": "email",
  "resource": "payment_methods"
}

type can be email or sms. The API responds 204 and sends a 6-digit code to the email or phone on your account. Pass that code as otp on the next request. You do not need a separate verify call.

Create a payment method

POST https://sandbox.ecartpay.com/api/payment-methods

Creating a Mexican CLABE checks that bank matches the CLABE. Ownership validation with RFC is a separate step (see Validate).

curl --location 'https://sandbox.ecartpay.com/api/payment-methods' \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "clabe",
    "name": "Personal",
    "number": "846180000400000001",
    "business_name": "John Doe",
    "bank": "40072",
    "country": "MX",
    "otp": "123456"
  }'

{
  "_id": "6255a30bd4b006320baff520",
  "account_id": "672a850371be0ecf554d050c",
  "method": "clabe",
  "name": "Personal",
  "number": "846180000400000001",
  "business_name": "John Doe",
  "bank": "40072",
  "country": "MX",
  "verified": true,
  "verification_request": false
}

If that number is already registered, the API returns 409 (That number is already in use). If you already have five methods, it returns 409 (You have exceeded the limit of allowed payment methods).

List payment methods

GET https://sandbox.ecartpay.com/api/payment-methods

Optional query: page, limit.

Account numbers in the list are masked (only the last four digits are visible). Use get-by-id for the full number.

{
  "docs": [
    {
      "_id": "6255a30bd4b006320baff520",
      "method": "clabe",
      "name": "Personal",
      "number": "***************0001",
      "bank": "40072",
      "country": "MX",
      "verified": true,
      "validation": {
        "status": "approved",
        "rfc": "EKU9003173C9"
      }
    }
  ],
  "totalDocs": 1,
  "limit": 10,
  "page": 1,
  "totalPages": 1
}

Get a payment method

GET https://sandbox.ecartpay.com/api/payment-methods/{id}

Returns the full number and the currency for that country (for example MXN).

Update a payment method

PUT https://sandbox.ecartpay.com/api/payment-methods/{id}

Include otp. You can change alias, number, bank, beneficiary name, and related fields.

You cannot update:

• Payment methods in India (IN)
• A Mexican CLABE whose validation.status is approved — delete it and create a new one

curl --location --request PUT 'https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520' \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Operating account",
    "business_name": "Acme Corp",
    "otp": "654321"
  }'

Validate a Mexican CLABE

PATCH https://sandbox.ecartpay.com/api/payment-methods/validate

Confirms that the CLABE belongs to the RFC you send. Available only for Mexican (MX) CLABE accounts.

The response sets validation.status to pending. When the bank confirmation finishes, you receive a webhook.

curl --location --request PATCH 'https://sandbox.ecartpay.com/api/payment-methods/validate' \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment_method_id": "6255a30bd4b006320baff520",
    "rfc": "EKU9003173C9",
    "otp": "123456"
  }'

{
  "_id": "6255a30bd4b006320baff520",
  "method": "clabe",
  "country": "MX",
  "validation": {
    "status": "pending",
    "rfc": "EKU9003173C9",
    "updated_at": "2026-08-31T16:00:00.000Z"
  }
}

If validation is already running, the API returns 409 (Payment method validation is already in progress.). If it is already approved, the same object is returned and no new validation is started.

validation.status values:

Request manual verification

PATCH https://sandbox.ecartpay.com/api/payment-methods/{id}/request-verification

Sets verification_request to true and notifies our compliance team. Use this when you need a manual review (for example a non-CLABE rail).

Delete a payment method

DELETE https://sandbox.ecartpay.com/api/payment-methods/{id}

{ "otp": "123456" }

{ "success": true }

You cannot delete your only payment method. Add another one first. If this destination is still required for an active payout setup and you have no other verified method, the API will reject the delete.

Past withdrawals keep a copy of the bank details so history is not lost.

Webhooks

Subscribe to:

• payment_method.validation_approved
• payment_method.validation_rejected

Verify x-pay-signature before you process the event. See Webhook authentication.

Example data:

{
  "message": "Payment method validation has been approved.",
  "payment_method_id": "6255a30bd4b006320baff520",
  "account_id": "672a850371be0ecf554d050c",
  "method": "clabe",
  "verified": true,
  "validation_status": "approved",
  "validation_type": "stp",
  "validated_at": "2026-08-31T16:05:00.000Z"
}

On reject, rejection_reason is included (for example RFC mismatch) and verified stays false.

Errors