Disbursements API

This API allows managing disbursement accounts towards clients or partners. It provides endpoints to create, read, update.

Disbursements are made automatically when a debt has been approved and generated.

The destination of the disbursement will depend on the product configuration (see DPA Products).

The CMS Base URL is used (see introduction).

The Disbursement Account Object

The Disbursement Account Object represents an account for electronic fund disbursement.

{
    "accountId": "55512717-110c-4801-bd5c-85d9cf401134",
    "clientId": "acd82a7f-9719-482a-846f-2d1db55b9bb4",
    "name": "BORROWER NAME",
    "taxId": "TAXID",
    "partnerId": "dff66815-5b16-4fed-a559-d320291c6e21",
    "type": "client",
    "bankAccount": {
        "accountNumber": "846180000400000001",
        "bankCode": "97846",
        "bankName": "STP",
        "accountType": 40
    },
    "status": "active",
    "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)
`clientId`	Client identifier (only included when the type is "client")	String (UUID)
`name`	Legal name of the account owner	String
`taxId`	Tax identifier of the account	String
`partnerId`	Identifier of the Partner managing the account	String (UUID)
`type`	Type of recipient account (client, partner)	String
`bankAccount`	Banking Information	Object
`status`	Account status	String
`createdAt`	Account creation date	String (Datetime)
`updatedAt`	Date of the last account update	String (Datetime)

Details of nested objects

bankAccount Object

Attribute	Description	Type
`accountNumber`	Bank account number	String (UUID)
`bankCode`	Issuing bank identifier	String
`bankName`	Name of the issuing bank	String
`accountType`	Corresponding account type	Integer

`accountType` Object

Type	Value	Description
`WireTransfer`	40	CLABE Account Type for countries like Mexico
`DebitCard`	3	Savings or Checking Account Type, traditional debit account
`MobilePhone`	10	Account Type associated with a phone number

`status` Object

State	Value	Description
`Created`	"created"	The account was created
`In Validation`	"in_validation"	The account is in the validation process
`Required Validation`	"required_validation"	The account requires manual validation
`Active`	"active"	The account is active and validated
`Rejected`	"rejected"	The account was rejected, this is due to the account data not matching the account holder
`Disabled`	"disabled"	The account is validated but deactivated
`Suspended`	"suspended"	The account is suspended for use, for security reasons

`bank` Object

Attribute	Description	Type
`bankCode`	Issuing bank identifier	String
`bankName`	Name of the issuing bank	String

Available Operations

List Available Banks

Retrieve a list of available banks.

GET /v1/disbursements/banks/:country

Path Parameters:

Parameter	Description	Type
`country`	Country ID in ISO format i.e MEX	string

Successful Response: The response will be a list of Bank objects.

Get Disbursement Accounts

GET /v1/disbursements/accounts/:country/:type/:ownerId

Path Parameters:

Parameter	Description	Type
`country`	Country ID in ISO format i.e MEX	string
`type`	Type of account to create `client` or `partner`	string
`ownerId`	Identifier of the account owner `clientId` or `partnerId`	string (UUID)
`x-partner-id`	Partner identifier sent as a header, required for client type	string (UUID)

Query Parameters:

Parameter	Description	Type
`status`	Status to filter the accounts to obtain see Status	String
`page`	Page number (default: 1)	Integer
`per-page`	Items per page (default: 10)	Integer
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response (200)

Returns an array of Disbursement Account objects.

Specific Errors

Response Code	Description
400	Invalid request. This can occur if required parameters are missing or if the provided values are not valid.

Get Disbursement Account

GET  /v1/disbursements/accounts/:country/:type/:ownerId/:accountId

Path Parameters:

Parameter	Description	Type
`country`	Country ID in ISO format i.e MEX	string
`type`	Type of account to create `client` or `partner`	string
`ownerId`	Identifier of the account owner `clientId` or `partnerId`	string (UUID)
`accountId`	Unique identifier of the account	string (UUID)
`x-partner-id`	Partner identifier sent as a header, required for client type	string (UUID)

Successful Response (200)

Returns a Disbursement Account object.

Specific Errors

Response Code	Description
400	Invalid request. This can occur if required parameters are missing or if the provided values are not valid.
404	The account does not exist

Create Disbursement Account

Creates a disbursement account.

Note: Multiple accounts can be created, but the system will deactivate any previously created (active) account.

POST /v1/disbursements/accounts/:country/:type

Path Parameters:

Parameter	Description	Type
`country`	Country ID in ISO format i.e MEX	string
`type`	Type of account to create client or partner	string

Input Parameters

Parameter	Description	Type	Required
`id`	ID of the account owner client or partner	String (UUID)	Yes
`partnerId`	Partner managing the account	String (UUID)	Yes
`bankAccount.accountNumber`	Account number	String	Yes
`bankAccount.accountType`	Bank Account Type	integer	Yes
`bankAccount.bankCode`	Issuing bank identifier of the account	String	No*
`bankAccount.bankName`	Issuing bank name of the account	String	No*
`name`	Legal name of the account owner	String	No*
`taxId`	Tax identifier of the account	String	No*

Notes:

The name parameter must be provided when the account type is partner.
The taxId parameter must be provided when the account type is partner.
When a request does not specify the bank code and bank name, the system will attempt to determine the bank code and bank name. This is only supported when the account type (accountType) is WireTransfer (40); for other account types, these values must be specified.

Request Body for a Client Type Account

{
    "id": "acd82a7f-9719-482a-846f-2d1db55b9bb4",
    "partnerId": "dff66815-5b16-4fed-a559-d320291c6e22",
    "bankAccount": {
        "accountNumber": "846180000400000001",
        "accountType": 40
    }
}

Request Body for a Partner Type Account

{
    "id":"dff66815-5b16-4fed-a559-d320291c6e22",
    "partnerId": "dff66815-5b16-4fed-a559-d320291c6e22",
    "name": "ALTSCORE LENDING",
    "taxId": "taxid",
    "bankAccount": {
        "accountNumber": "846180000400000001",
        "accountType": 40
    }
}

Successful Response (201)

The response includes a created Disbursement Account object.

Specific Errors

Response Code	Description
400	Invalid request. This can occur if required parameters are missing or if the provided values are not valid.
404	The `client` or `partner` does not exist
409	Another account is associated with the same bank account and/or duplicate account
403	Not allowed, the user does not have access to read clients of the partner

In case of error, the response will include details about the nature of the problem to assist in resolution.

Update an Account

An account's banking information can be updated when it is in the Rejected status. Once the account is active/validated, no further changes can be made.

PATCH  /v1/disbursements/accounts/:country/:type/:ownerId/:accountId

Path Parameters:

Parameter	Description	Type
`country`	Country ID in ISO format i.e MEX	string
`type`	Type of account to create `client` or `partner`	string
`ownerId`	Identifier of the account owner `clientId` or `partnerId`	string (UUID)
`accountId`	Unique identifier of the account	string (UUID)
`x-partner-id`	Partner identifier sent as a header, required for client type	string (UUID)

Input Parameters

Parameter	Description	Type	Required
`bankAccount.accountNumber`	Account number	String	Yes
`bankAccount.accountType`	Bank account type	integer	Yes
`bankAccount.bankCode`	Issuing bank identifier of the account	String	No*
`bankAccount.bankName`	Issuing bank name of the account	String	No*
`name`	Legal name of the account owner	String	No*
`taxId`	Tax identifier of the account	String	No*
`status`	The account status (active, disabled), to activate/deactivate the account	String	No*

Notes:

The name parameter must be provided when the account type is partner.
The taxId parameter must be provided when the account type is partner.
When a request does not specify the bank code and bank name, the system will attempt to determine the bank code and bank name. This is only supported when the account type (accountType) is WireTransfer (40); for other account types, these values must be specified.
When changing the status to active, the previously active account changes to disabled.
Only one active account is allowed; only previously validated accounts can be activated and deactivated.

Successful Response (200)

Returns a Disbursement Account object.

Specific Errors

Response Code	Description
400	Invalid request. This can occur if required parameters are missing or if the provided values are not valid.
404	The account does not exist
409	Another account is associated with the same bank account and/or duplicate account
403	Not allowed, the user does not have access to read clients of the partner

Delete an Account

DELETE  /v1/disbursements/accounts/:country/:type/:ownerId/:accountId

Path Parameters:

Parameter	Description	Type
`country`	Country ID in ISO format i.e MEX	string
`type`	Type of account to create `client` or `partner`	string
`ownerId`	Identifier of the account owner `clientId` or `partnerId`	string (UUID)
`accountId`	Unique identifier of the account	string (UUID)
`x-partner-id`	Partner identifier sent as a header, required for client type	string (UUID)

Successful Response (204)

Successful request (NoContent)

Specific Errors

Response Code	Description
400	Invalid request. This can occur if required parameters are missing or if the provided values are not valid.
404	The `client` or `partner` does not exist
409	Another account is associated with the same bank account and/or duplicate account
403	Not allowed, the user does not have access to read clients of the partner

The Disbursement Object

The Disbursement Object represents a fund disbursement.

{
    "gateway": "stp",
    "amountTransferred": {
        "amount": "100.00",
        "currency": "MXN",
        "display": "$100.00"
    },
    "beneficiary": {
        "accountNumber": "846155663598702501",
        "name": "Mr. Beneficiary",
        "institution": "88562",
        "institutionName": "STP",
        "rfcCurp": "taxid"
    },
    "payer": {
        "accountNumber": "646189844251369575",
        "name": "Mr. Payer",
        "institution": "84623",
        "institutionName": "STP",
        "rfcCurp": "XXX2501319Z9"
    },
    "notes": "optional notes",
    "paymentDate": "2025-03-03T19:01:12.612Z",
    "status": "failed",
    "referenceNumber": 9124,
    "confirmationId": "",
    "trackingKey": "FIA0000000000001",
    "payOrderId": "62913f04-da4a-4069-94a3-6377a34dd846",
    "debtId": "29eed03e-19cc-43d8-b176-f86856d75a46",
    "partner": {
        "partnerId": "1c57aa03-9696-4c99-8eb3-956b23557d35",
        "name": "Partner Name",
        "taxId": "XAXX010101000"
    },
    "client": {
        "clientId": "4bcf9948-708c-4113-964d-ac07a45ef81e",
        "externalId": "128d6869-3497-4b92-afa4-1fc9849e6fbf",
        "legalName": "Client Name",
        "taxId": "20-44556677-8"
    },
    "amount": {
        "amount": "100.00",
        "currency": "MXN",
        "display": "$100.00"
    },
    "disbursementDate": "2025-03-03T00:00:00Z",
    "referenceId": "ALT-0001",
    "createdAt": "2025-03-03T19:01:12.612Z",
    "updatedAt": "2025-03-03T19:01:14.908Z",
    "version": 1
}

Get a Disbursement

Retrieve information about a specific disbursement.

GET /v1/disbursements/:payOrderId

Path Parameters:

Parameter	Description
`payOrderId`	ID of the disbursement to retrieve

Successful Response:

The response will be a Disbursement object.

List Disbursements

Retrieve a list of disbursements.

GET /v1/disbursements

Query Parameters:

Parameter	Description	Type
`partner-id`	Filter by partner ID	String
`debt-id`	Filter by debt ID	String
`status`	Filter by disbursement status	String
`tracking-key`	Filter by tracking key	String
`reference-num`	Filter by reference number	String
`from-date`	Filter by start date	String
`to-date`	Filter by end date	String
`page`	Page number (default: 1)	Integer
`per-page`	Items per page (default: 10)	Integer
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response:

The response will be a list of Disbursement objects.

Update a Disbursement as Successful

Update its status as long as its current status is sent.

PUT /v1/disbursements/:payOrderId/success

Path Parameters:

Parameter	Description
`payOrderId`	ID of the disbursement to update

Successful Response:

Successful request (204 - NoContent)

Reconcile a Disbursement

Reconcile a specific disbursement as long as its current status is sent or success.

PUT /v1/disbursements/:payOrderId/reconcile

Path Parameters:

Parameter	Description
`payOrderId`	ID of the disbursement to reconcile

Successful Response:

Successful request (204 - NoContent)

accountType Object

status Object

bank Object

On this page

`accountType` Object

`status` Object

`bank` Object