Payments API

This API allows managing payments received for customers. It provides endpoints to query and manage payments made through payment accounts.

The CMS Base URL is used (see introduction).

The Payment Object
The PaymentApplication Object
Payment Operations
Status Values
- Payment Statuses
- Application Statuses

The Payment Object

The Payment object represents a payment made by a customer and contains detailed information about the transaction.

Attribute	Description	Type
`tenantId`	Tenant identifier	String
`paymentId`	Unique payment identifier	String (UUID)
`clientId`	Customer identifier	String (UUID)
`partnerId`	Partner identifier	String (UUID)
`reference`	Payment reference used	String
`provider`	Payment service provider	String
`transactionId`	Transaction identifier	String (UUID)
`sourceTransactionId`	Source system transaction identifier	String
`amount`	Payment amount without fees or taxes	Object
`fees`	Payment fees	Object
`taxes`	Payment taxes	Object
`total`	Total payment amount (amount + fees + taxes)	Object
`createdAt`	Record creation date	String (Datetime)
`updateAt`	Last update date	String (Datetime)
`transactionDate`	Transaction date	String (Datetime)
`receivedAt`	Payment receipt date	String (Datetime)
`processingAt`	Payment processing date	String (Datetime)
`status`	Payment status (see status table)	String
`remain`	Remaining amount not applied	Object
`applications`	List of payment applications to debts	Array

The PaymentApplication Object

Attribute	Description	Type
`paymentApplicationId`	Payment application identifier	String (UUID)
`debtId`	Debt identifier	String (UUID)
`creditSourceSystem`	Credit source system	String
`amount`	Amount applied to the debt	Object
`applicationDate`	Application date	String (Date)
`createdAt`	Application creation date	String (Datetime)
`reference`	Application reference	String
`notes`	Notes or comments about the application	String
`status`	Application status (see status table)	String
`appliedAt`	Date and time when it was applied (optional)	String (Datetime)

Payment Operations

Get Customer Payments

Retrieves the list of payments made by a specific customer.

GET /v1/payments/{partnerId}

Path Parameters

Parameter	Description	Type	Required
`partnerId`	Partner identifier	String (UUID)	Yes

Query Parameters

Parameter	Description	Type
`client-id`	Comma-separated list of client IDs	UUID Array
`status`	Filter by Payment Status	String Array
`provider`	Filter by provider	String
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response (200)

The response includes an array of Payment objects associated with the customer.

Specific Errors

Response Code	Description
400	Invalid request. This can occur if the provided values are not valid.
404	No payments found for the specified customer.

Example of Payment Response

Below is an example of the response obtained when querying a customer's payments:

[
    {
        "tenantId": "tenant-123",
        "paymentId": "123e4567-e89b-12d3-a456-426614174000",
        "clientId": "965117da-f8cf-42b6-b8c2-3665a8029b36",
        "partnerId": "0ab1aeac-2145-4096-9435-4768c5ebb579",
        "reference": "1234567890",
        "provider": "PAYNET",
        "transactionId": "123e4567-e89b-12d3-a456-426614174111",
        "sourceTransactionId": "TX123456789",
        "amount": {
            "amount": 1000,
            "currency": "MXN"
        },
        "fees": {
            "amount": 50,
            "currency": "MXN"
        },
        "taxes": {
            "amount": 160,
            "currency": "MXN"
        },
        "total": {
            "amount": 1210,
            "currency": "MXN"
        },
        "createdAt": "2024-11-12T20:31:45.96382213Z",
        "updateAt": "2024-11-12T20:35:45.96382213Z",
        "transactionDate": "2024-11-12T20:30:45.96382213Z",
        "receivedAt": "2024-11-12T20:31:45.96382213Z",
        "processingAt": "2024-11-12T20:32:45.96382213Z",
        "status": "APPLIED",
        "remain": {
            "amount": 0,
            "currency": "MXN"
        },
        "applications": [
            {
                "paymentApplicationId": "123e4567-e89b-12d3-a456-426614174222",
                "debtId": "123e4567-e89b-12d3-a456-426614174333",
                "creditSourceSystem": "dpa",
                "amount": {
                    "amount": 1000,
                    "currency": "MXN"
                },
                "applicationDate": "2024-11-12",
                "createdAt": "2024-11-12T20:33:45.96382213Z",
                "reference": "REF-123456",
                "notes": "Monthly fee payment",
                "status": "APPLIED",
                "appliedAt": "2024-11-12T20:34:15.96382213Z"
            }
        ]
    }
]

Get a Payment

Retrieves detailed information of a specific payment.

GET /v1/payments/{partnerId}/{paymentId}

Path Parameters

Parameter	Description	Type	Required
`partnerId`	Partner identifier	String (UUID)	Yes
`paymentId`	Payment identifier	String (UUID)	Yes

Successful Response (200)

The response includes a Payment object.

Re-process Payments

Allows re-processing a specific payment in case a debt has not been applied, as long as the payment status is CREATED or IN_PROCESS.

PUT /v1/payments/{partnerId}/{paymentId}/retry

Path Parameters

Parameter	Description	Type	Required
`partnerId`	Partner identifier	String (UUID)	Yes
`paymentId`	Payment identifier	String (UUID)	Yes

Input Parameters

Parameter	Description	Type	Required
`date`	Date on which to apply the payment	String (YYYY-MM-DD)	No*

Successful Response (202)

The payment has been added to the re-processing queue.

Specific Errors

Response Code	Description
400	Invalid request. This can occur if the provided values are not valid.
404	Payment not found.
409	Payment cannot be re-processed

Status Values

Payment Statuses

Possible values for the status field in payments:

Status	Value	Description
`Created`	"CREATED"	The payment has been created but not yet processed
`Applied`	"APPLIED"	The payment has been successfully applied
`Rejected`	"REJECTED"	The payment has been rejected
`Invalid`	"INVALID"	The payment is invalid
`In Process`	"IN_PROCESS"	The payment is being processed
`Reverted`	"REVERTED"	The payment has been reverted
`Duplicated`	"DUPLICATED"	The payment is a duplicate of an existing one
`To Revert`	"TO_REVERT"	The payment is marked to be reverted

Application Statuses

Possible values for the status field in payment applications:

Status	Value	Description
`In Process`	"IN_PROCESS"	The application is being processed
`Rejected`	"REJECTED"	The application has been rejected
`Applied`	"APPLIED"	The application has been successfully applied to the debt

Payments API

Table of Contents

The Payment Object

The PaymentApplication Object

Payment Operations

Get Customer Payments

Path Parameters

Query Parameters

Successful Response (200)

Specific Errors

Example of Payment Response

Get a Payment

Path Parameters

Successful Response (200)

Re-process Payments

Path Parameters

Input Parameters

Successful Response (202)

Specific Errors

Status Values

Payment Statuses

Application Statuses

On this page