Documentation

Payment Methods

Adding a payment method to your Ecart Pay account allows you to manage withdrawals effectively. You can set up a debit card or a bank account using a CLABE number.

Managing financial transactions efficiently is crucial for any business. This system supports the addition of multiple payment method types including CLABE accounts for Mexico, ACH transfers for the US, and SEPA transfers for Europe. By integrating payment methods into your account, you can centralize financial operations, reduce errors, and save time.

Key Parameters

ParameterTypeRequiredDescription
methodstringYesSpecifies the type of payment method: clabe (Mexico), ach (US), sepa (Europe), wire, debit, etc.
namestringYesA user-defined label for the payment method, making it easier to identify, such as "Personal" or "Business". Represents a Payment Method alias.
numberstringYesThe account number, CLABE, or card number for the payment method.
business_namestringNoRepresents the account beneficiary name.
bankstringConditionalThe bank code. Required for CLABE accounts (unless bank_name is provided for non-MX countries). For Mexican bank codes, see: Banks
bank_namestringConditionalRequired for non-Mexican countries when bank is not provided.
countrystringNoISO country code (e.g., MX, US, CO). Inferred from account if not provided.
rfcstringConditionalRequired for Mexican CLABE accounts (method: clabe, country: MX). Must be a valid RFC format.
otpstringYesOne-time password for security verification. Required for create and update operations.
routingstringNoRouting number for US ACH transfers.
dnistringNoDocument identification number.
dni_typestringNoType of identification document.
rutstringNoRUT number for Chilean accounts.
bank_branchstringNoBank branch information.

⚠️

IMPORTANT

To follow the steps below, it is essential to have the corresponding Authorization Token and proper scopes. For more information, please refer to the following documentation page: Authorization Token

Required Scopes:

  • write_payment_methods - For create, update, delete, validate, and request verification operations
  • read_payment_methods - For listing and retrieving payment methods

Create New Payment Method

This endpoint enables you to add a new payment method for withdrawals. Supported methods include CLABE (Mexico), ACH (US), SEPA (Europe), and wire transfers.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • POST {{baseURL}}/api/payment-methods
  • POST https://sandbox.ecartpay.com/api/payment-methods

Headers

  • Authorization: {token}
  • Content-Type: application/json

Request

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

Response

 {
    "_id": "6255a30bd4b006320baff520",
    "account_id": "672a850371be0ecf554d050c",
    "method": "clabe",
    "name": "Personal",
    "number": "846180000400000001",
    "business_name": "John Doe",
    "bank": "40072",
    "country": "MX",
    "verified": false,
    "verification_request": false,
    "validation": {
        "status": "pending",
        "rfc": "ABCD010101ABC",
        "updated_at": "2025-01-15T10:30:00.000Z"
    },
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
}




List All Payment Methods

Retrieve a paginated list of all payment methods associated with your account. Account numbers are masked (only the last 4 digits are shown) for security.

💻

Visit our API Reference to test this endpoint.

Endpoint

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

Headers

  • Authorization: {token}
  • Content-Type: application/json

Query Parameters (Optional)

ParameterTypeDescription
limitnumberNumber of results per page (default: 10)
pagenumberPage number (default: 1)

Request

curl --location 'https://sandbox.ecartpay.com/api/payment-methods' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json'

Response

{
    "docs": [
        {
            "_id": "6255a30bd4b006320baff520",
            "account_id": "672a850371be0ecf554d050c",
            "method": "clabe",
            "name": "Personal",
            "number": "***************0001",
            "business_name": "John Doe",
            "bank": "40072",
            "country": "MX",
            "verified": true,
            "verification_request": false,
            "validation": {
                "status": "approved",
                "rfc": "ABCD010101ABC",
                "updated_at": "2025-01-15T10:30:00.000Z"
            },
            "created_at": "2025-01-15T10:30:00.000Z",
            "updated_at": "2025-01-15T10:30:00.000Z"
        }
    ],
    "totalDocs": 1,
    "limit": 10,
    "page": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
}
📘

Note

In the list view, account numbers are masked for security. Use the Get Single Payment Method endpoint to retrieve the full unmasked number.





Get Single Payment Method

Retrieve detailed information about a specific payment method by its ID.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • GET {{baseURL}}/api/payment-methods/{id}
  • GET https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520

Path Parameters

ParameterTypeDescription
idstringThe unique identifier of the payment method

Headers

  • Authorization: {token}
  • Content-Type: application/json

Request

curl --location 'https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json'

Response

{
    "_id": "6255a30bd4b006320baff520",
    "account_id": "672a850371be0ecf554d050c",
    "currency": "MXN",
    "method": "clabe",
    "name": "Personal",
    "number": "846180000400000001",
    "business_name": "John Doe",
    "bank": "40072",
    "country": "MX",
    "verified": true,
    "verification_request": false,
    "validation": {
        "status": "approved",
        "rfc": "ABCD010101ABC",
        "stp_order_id": "abc123",
        "updated_at": "2025-01-15T10:30:00.000Z"
    },
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
}




Update Payment Method

Update the details of an existing payment method. Note that Mexican CLABE accounts that have been approved by STP cannot be updated - you must delete and recreate them.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • PUT {{baseURL}}/api/payment-methods/{id}
  • PUT https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520

Path Parameters

ParameterTypeDescription
idstringThe unique identifier of the payment method to update

Headers

  • Authorization: {token}
  • Content-Type: application/json

Request

curl --location --request PUT 'https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Business Account",
    "number": "846180000400000002",
    "business_name": "Acme Corp",
    "bank": "40012",
    "otp": "654321"
}'

Response

{
    "_id": "6255a30bd4b006320baff520",
    "account_id": "672a850371be0ecf554d050c",
    "method": "clabe",
    "name": "Business Account",
    "number": "846180000400000002",
    "business_name": "Acme Corp",
    "bank": "40012",
    "country": "MX",
    "verified": false,
    "validation": {
        "status": "pending",
        "rfc": "ABCD010101ABC",
        "updated_at": "2025-01-15T11:00:00.000Z"
    },
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z"
}
❗️

IMPORTANT RESTRICTIONS

  • Indian (IN) payment methods cannot be updated.
  • Mexican CLABE accounts with validation.status: "approved" cannot be edited. Delete and create a new one if needed.






Validate Payment Method

Manually trigger validation for a Mexican CLABE payment method. This endpoint is primarily used to re-validate accounts or provide an RFC if it wasn't included during creation.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • PATCH {{baseURL}}/api/payment-methods/validate
  • PATCH https://sandbox.ecartpay.com/api/payment-methods/validate

Headers

  • Authorization: {token}
  • Content-Type: application/json

Request

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

Response

{
    "_id": "6255a30bd4b006320baff520",
    "account_id": "672a850371be0ecf554d050c",
    "method": "clabe",
    "name": "Personal",
    "number": "846180000400000001",
    "business_name": "John Doe",
    "bank": "40072",
    "country": "MX",
    "validation": {
        "status": "pending",
        "rfc": "ABCD010101ABC",
        "stp_order_id": "xyz789",
        "_id": "678901234567890123456789",
        "updated_at": "2025-01-15T12:00:00.000Z"
    },
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T12:00:00.000Z"
}
📘

NOTE

Validation is only available for Mexican (MX) payment methods. The validation process communicates with STP (Sistema de Transferencias y Pagos) to verify the account ownership.






Request Verification

Request manual verification for a payment method. This triggers a notification to the compliance team for manual review.

💻

Visit our API Reference to test this endpoint.

Endpoint

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

Path Parameters

ParameterTypeDescription
idstringThe unique identifier of the payment method

Headers

  • Authorization: {token}
  • Content-Type: application/json

Request

curl --location --request PATCH 'https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520/request-verification' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json'

Response

{
    "_id": "6255a30bd4b006320baff520",
    "account_id": "672a850371be0ecf554d050c",
    "method": "clabe",
    "name": "Personal",
    "number": "846180000400000001",
    "business_name": "John Doe",
    "bank": "40072",
    "country": "MX",
    "verified": false,
    "verification_request": true,
    "validation": {
        "status": "pending",
        "rfc": "ABCD010101ABC"
    },
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T12:30:00.000Z"
}

📘

NOTE

The verification_request flag is set to true and a notification is sent to the compliance team for manual review.







Delete Payment Method

Remove a payment method from your account. You cannot delete your only payment method - you must have at least one alternative method configured first.

💻

Visit our API Reference to test this endpoint.

Endpoint

  • DELETE {{baseURL}}/api/payment-methods/{id}
  • DELETE https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520

Path Parameters

ParameterTypeDescription
idstringThe unique identifier of the payment method to delete

Headers

  • Authorization: {token}
  • Content-Type: application/json

Request

curl --location --request DELETE 'https://sandbox.ecartpay.com/api/payment-methods/6255a30bd4b006320baff520' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json'

Response

{
    "success": true
}
❗️

IMPORTANT

  • You cannot delete your only payment method. Add another method first.
  • If the payment method has associated withdrawals, the withdrawal records will be updated to preserve the payment method information for historical purposes.

Updated 14 days ago