Payment Accounts API

This API allows managing payment accounts for customers. It provides endpoints to create, read, and manage accounts and payment references.

Payment accounts function as a unique or universal account for a customer, with multiple payment references to accept payments for credits/loans through different methods. Currently, two payment providers are supported:

DAPP: For cash payments through physical stores
STP: For electronic bank transfers

The CMS Base URL is used (see introduction).

The Account Object
The AccountReference Object
Payment Account Operations
Status Values
- Reference Statuses
Supported Providers

The Account Object

The Account Object represents an account for receiving payments from different sources and methods.

{
    "accountId": "55512717-110c-4801-bd5c-85d9cf401134",
    "accountHolder": {
        "name": "JOHN DOE",
        "phone": "+5215512345678",
        "email": "john.doe@example.com",
        "partnerId": "0ab1aeac-2145-4096-9435-4768c5ebb579",
        "clientId": "965117da-f8cf-42b6-b8c2-3665a8029b36"
    },
    "references": [
        {
            "accountReferenceId": "10000000400000001",
            "gatewayId": "f8512717-110c-4801-bd5c-85d9cf401555",
            "provider": "dapp",
            "status": "active",
            "amount": {
                "amount": 1000,
                "currency": "MXN"
            },
            "reference": "1234567890",
            "createdAt": "2024-11-12T20:31:45.96382213Z",
            "updatedAt": "2024-11-12T20:31:45.963823237Z",
            "expirationAt": "2024-12-12T20:31:45.963823237Z"
        },
        {
            "accountReferenceId": "846180000400000002",
            "gatewayId": "e7722717-110c-4801-bd5c-85d9cf401666",
            "provider": "stp",
            "status": "active",
            "reference": "646180000400000001",
            "createdAt": "2024-11-12T20:31:45.96382213Z"
        }
    ],
    "createdAt": "2024-11-12T20:31:45.96382213Z",
    "updatedAt": "2024-11-12T20:31:45.963823237Z"
}

Attributes

Attribute	Description	Type
`accountId`	Unique identifier of the account	String (UUID)
`accountHolder`	Account holder information	Object
`references`	List of payment references associated with the account	Array
`createdAt`	Account creation date	String (Datetime)
`updatedAt`	Date of the last account update	String (Datetime)

Nested Object Details

accountHolder Object

Attribute	Description	Type
`name`	Account holder's name	String
`phone`	Account holder's phone number (optional)	String
`email`	Account holder's email (optional)	String
`partnerId`	Partner identifier managing the account	String (UUID)
`clientId`	Client identifier	String (UUID)

The AccountReference Object

The AccountReference object represents a payment reference associated with an account.

Attribute	Description	Type
`accountReferenceId`	Unique identifier of the reference	String (UUID)
`gatewayId`	Payment gateway identifier	String (UUID)
`provider`	Payment service provider (see providers table)	String
`status`	Payment reference status (see reference statuses)	String
`amount`	Amount associated with the reference (optional)	Object
`reference`	Reference code for making the payment	String
`createdAt`	Reference creation date	String (Datetime)
`updatedAt`	Reference update date	String (Datetime)
`expirationAt`	Reference expiration date (optional)	String (Datetime)

amount Object

Attribute	Description	Type
`amount`	Numeric amount	Number
`currency`	Currency code (e.g., MXN)	String

Payment Account Operations

Create Payment Account

Creates a payment account for a specific customer.

POST /v1/accounts

Input Parameters

Parameter	Description	Type	Required
`partnerId`	Partner identifier managing the account	String (UUID)	Yes
`clientId`	Client identifier	String (UUID)	Yes
`customerName`	Customer's name	String	No
`customerPhone`	Customer's phone number	String	No
`customerEmail`	Customer's email	String	No
`autoCreateReferences`	Automatically create references for configured payment methods	Boolean	No

Request Body

{
    "partnerId": "0ab1aeac-2145-4096-9435-4768c5ebb579",
    "clientId": "965117da-f8cf-42b6-b8c2-3665a8029b36",
    "customerName": "John Doe",
    "customerPhone": "+5215512345678",
    "customerEmail": "john.doe@example.com",
    "autoCreateReferences": true
}

Successful Response (201)

The response includes a created Account object with its payment references.

Specific Errors

Response Code	Description
400	Invalid request. This may occur if required parameters are missing or if the provided values are not valid.
404	The `client` or `partner` does not exist
409	An account already exists for the specified customer

Get Payment Account

Retrieves the information of a payment account for a specific customer.

GET /v1/accounts/{client-id}

Path Parameters

Parameter	Description	Type	Required
`client-id`	Client identifier	String (UUID)	Yes

Successful Response (200)

The response includes an Account object with all its information and payment references of type AccountReference.

Specific Errors

Response Code	Description
400	Invalid request. This may occur if the provided values are not valid.
404	The account does not exist for the specified customer.

Get Payment References

Retrieves the payment references associated with a specific customer account.

GET /v1/accounts/{client-id}/references

Path Parameters

Parameter	Description	Type	Required
`client-id`	Client identifier	String (UUID)	Yes

Query Parameters

Parameter	Description	Type	Required
`status`	Filter by reference status	String	No
`provider`	Filter by reference provider	String	No

Successful Response (200)

The response includes an array of AccountReference objects associated with the customer's account.

Specific Errors

Response Code	Description
400	Invalid request. This may occur if the provided values are not valid.
404	The account does not exist for the specified customer.

Create Payment Reference

Creates a new payment reference for an existing account.

POST /v1/accounts/{client-id}/references

Path Parameters

Parameter	Description	Type	Required
`client-id`	Client identifier	String (UUID)	Yes

Input Parameters

Parameter	Description	Type	Required
`provider`	Payment service provider (dapp, stp)	String	No
`gatewayId`	Payment gateway identifier	String (UUID)	No
`amount`	Amount associated with the reference	Object	No
`durationDays`	Duration in days of the reference's validity	Integer	No

Request Body

The request body must contain the necessary details to create a payment reference.

{
    "provider": "PAYNET",
    "gatewayId": "f8512717-110c-4801-bd5c-85d9cf401555",
    "amount": {
        "amount": 1000,
        "currency": "MXN"
    },
    "durationDays": 30
}

Successful Response (201)

The response includes an array of created AccountReference objects:

[
    {
        "accountReferenceId": "846180000400000001",
        "gatewayId": "f8512717-110c-4801-bd5c-85d9cf401555",
        "provider": "PAYNET",
        "status": "ACTIVE",
        "amount": {
            "amount": 1000,
            "currency": "MXN"
        },
        "reference": "1234567890",
        "createdAt": "2024-11-12T20:31:45.96382213Z",
        "updatedAt": "2024-11-12T20:31:45.963823237Z",
        "expirationAt": "2024-12-12T20:31:45.963823237Z"
    },
    {
        "accountReferenceId": "846180000400000002",
        "gatewayId": "e7722717-110c-4801-bd5c-85d9cf401666",
        "provider": "STP",
        "status": "ACTIVE",
        "reference": "646180000400000001",
        "createdAt": "2024-11-12T20:31:45.96382213Z"
    }
]

Specific Errors

Response Code	Description
400	Invalid request. This may occur if required parameters are missing or if the provided values are not valid.
404	The account does not exist.
409	A reference with the same parameters already exists.
422	Unprocessable entity. Error in processing the request.

Status Values

Reference Statuses

Possible values for the status field in payment references:

Status	Value	Description
`Active`	"ACTIVE"	The reference is active and can receive payments
`Cancelled`	"CANCELLED"	The reference has been cancelled
`Expired`	"EXPIRED"	The reference has expired

Supported Payment Providers

Possible values for the provider field in payment references:

Provider	Value	Description
DAPP	"dapp"	Cash payments through physical stores
STP	"stp"	Electronic bank transfers

Payment Accounts API

Table of Contents

The Account Object

Attributes

The AccountReference Object

Payment Account Operations

Create Payment Account

Input Parameters

Request Body

Successful Response (201)

Specific Errors

Get Payment Account

Path Parameters

Successful Response (200)

Specific Errors

Get Payment References

Path Parameters

Query Parameters

Successful Response (200)

Specific Errors

Create Payment Reference

Path Parameters

Input Parameters

Request Body

Successful Response (201)

Specific Errors

Status Values

Reference Statuses

Supported Payment Providers

On this page