DPA Flow API

This API allows managing Deferred Payment Agreement (DPA) flows in the system. It provides endpoints to create, read, update, and manage DPA flows, as well as to perform simulations and specific operations such as approval, cancellation, and closure of flows.

The CMS Base URL is used (see introduction).

The Flow Object

The Flow object represents a Deferred Payment Agreement (DPA) flow in the system. This flow describes the financing request, the agreed terms, and the payment plan associated with a specific transaction.

{
    "flowId": "a3a424c6-e34c-4519-933a-7e44fb016c40",
    "tenant": "altscore",
    "client": {
        "clientId": "c6138660-eb0b-4ff4-b2d5-f3b2cedf0298",
        "externalId": "cli:123456",
        "legalName": "Kiosco La Esquina",
        "partnerId": "648292b4-cbb9-4fb5-9dbe-a3aa5c02f1b8"
    },
    "referenceId": "PO-1234",
    "terms": {
        "principal": {
            "amount": "100000.00",
            "currency": "ARS"
        },
        "repayEvery": 15,
        "interestRate": {
            "period": 360,
            "rate": "120.0000"
        },
        "installments": 2,
        "amortizationType": "equal_total",
        "disbursementDate": "2023-10-22",
        "interestTax": 21,
        "timezone": "America/Argentina/Buenos_Aires",
        "calendarType": "BusinessDays",
        "loanTermDuration": 30
    },
    "schedule": [
        {
            "number": 1,
            "dueDate": "2023-11-06",
            "originalAmounts": {
                "principal": {
                    "amount": "25000.00",
                    "currency": "ARS"
                },
                "interest": {
                    "amount": "1250.00",
                    "currency": "ARS"
                },
                "fees": {
                    "amount": "0.00",
                    "currency": "ARS"
                },
                "taxes": {
                    "amount": "0.00",
                    "currency": "ARS"
                },
                "total": {
                    "amount": "26250.00",
                    "currency": "ARS"
                }
            }
        },
        {
            "number": 2,
            "dueDate": "2023-11-21",
            "originalAmounts": {
                "principal": {
                    "amount": "25000.00",
                    "currency": "ARS"
                },
                "interest": {
                    "amount": "1250.00",
                    "currency": "ARS"
                },
                "fees": {
                    "amount": "0.00",
                    "currency": "ARS"
                },
                "taxes": {
                    "amount": "0.00",
                    "currency": "ARS"
                },
                "total": {
                    "amount": "26250.00",
                    "currency": "ARS"
                }
            }
        }
    ],
    "status": "pending",
    "createdAt": "2023-10-30T22:13:37.047955596Z",
    "updatedAt": "2023-10-30T22:13:37.047974612Z"
}

Attributes

Attribute	Description	Type
`flowId`	Unique identifier of the DPA flow	String (UUID)
`tenant`	Tenant identifier in the system	String
`client`	Information about the client associated with the flow	Object
`referenceId`	External reference identifier (e.g., purchase order)	String
`terms`	Terms of the deferred payment agreement	Object
`schedule`	Payment plan of the agreement	Array of Object
`status`	Current status of the flow	String
`createdAt`	Date and time of flow creation	String (ISO 8601)
`updatedAt`	Date and time of the last flow update	String (ISO 8601)

Detail of nested objects

client Object

Attribute	Description	Type
`clientId`	Unique identifier of the client	String (UUID)
`externalId`	External identifier of the client	String
`legalName`	Legal name of the client	String
`partnerId`	Identifier of the partner associated with the client	String (UUID)

terms Object

Attribute	Description	Type
`principal`	Principal amount of the agreement	Object
`repayEvery`	Payment frequency in days	Integer
`interestRate`	Applied interest rate	Object
`installments`	Number of installments	Integer
`amortizationType`	Type of amortization	String
`disbursementDate`	Disbursement date	String (YYYY-MM-DD)
`interestTax`	Interest tax percentage	Number
`timezone`	Applicable timezone	String
`calendarType`	Calendar type for date calculations	String ("Custom", "BusinessDays", "NaturalDays")
`loanTermDuration`	Total loan duration in days	Integer

schedule Object (Array)

Each element of the schedule array represents an installment and contains:

Attribute	Description	Type
`number`	Installment number	Integer
`dueDate`	Installment due date	String (YYYY-MM-DD)
`originalAmounts`	Original amounts of the installment	Object

The originalAmounts object contains the following fields, each with amount and currency:

principal: Capital amount
interest: Interest amount
fees: Fees amount
taxes: Taxes amount
total: Total installment amount

Possible statuses (status)

pending: The flow is pending confirmation
approved: The flow has been approved and is ready to generate debts
partially-confirmed: The flow is confirmed and at least one debt has been created
confirmed: The flow is confirmed and all debts have been created
rejected: The flow has been rejected and no debts were created
closed: The flow has been closed without creating debts
canceled: The flow has been canceled

Available Operations

List DPA Flows

Retrieves a paginated list of DPA flows with filtering and sorting options.

GET /v1/dpas

Query Parameters:

Parameter	Description	Type
`client-id`	Specific client IDs	Array
`external-id`	Client's external identifier	String
`status`	Filter by flow status	Array
`expired-from`	Start date for expired flows	String
`expired-to`	End date for expired flows	String
`sort-by`	Field to sort by	String
`page`	Page number	Integer
`per-page`	Items per page	Integer
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response:

The response will be a paginated list of Flow objects.

Simulate a DPA Flow

This operation allows performing a simulation of a Deferred Payment Agreement (DPA) for a specific client.

POST /v1/dpas/simulations

Request Body with `productId`

{
  "amount": {
    "amount": "10000.00",
    "currency": "ARS"
  },
  "clientId": "e732bc5f-5b84-4a0a-81b4-5354d4625a8b",
  "externalId": "CLI-12345",
  "disbursementDate": "2023-04-15",
  "productId": "dd58d928-b836-494b-9f0c-05919f001791"
}

Request Body with `terms`

{
  "amount": {
    "amount": "10000.00",
    "currency": "ARS"
  },
  "clientId": "e732bc5f-5b84-4a0a-81b4-5354d4625a8b",
  "externalId": "CLI-12345",
  "disbursementDate": "2023-04-15",
  "terms": {
    "amortizationType": "equal_total",
    "installments": 3,
    "repayEvery": 30,
    "interestRate": {
      "rate": "15.00",
      "period": 360
    },
    "interestTax": 21,
    "interestCalculateType": "period"
  }
}

Input Parameters

Parameter	Description	Type	Required
`amount`	Agreement amount	Object	Yes
`amount.amount`	Amount value	String	Yes
`amount.currency`	Amount currency	String	Yes
`clientId`	Client ID in the system	String (UUID)	No*
`externalId`	Client's external ID in the partner's system	String	No*
`disbursementDate`	Proposed disbursement date	String (YYYY-MM-DD)	No
`productId`	Credit product ID to use	String (UUID)	No*
`terms`	Proposed terms for the agreement	Object	No*
`terms.amortizationType`	Amortization type ("equal_total" or French amortization)	String	Yes
`terms.installments`	Number of installments	Integer	No
`terms.repayEvery`	Payment frequency in days	Integer	No
`terms.interestRate`	Interest rate configuration	Object	No
`terms.interestRate.rate`	Interest rate value	String	No
`terms.interestRate.period`	Interest rate period in days	Integer	No
`terms.interestTax`	Interest tax rate	Number	No
`terms.interestCalculateType`	Interest calculation type. Defines how and when interests are calculated and applied. (default: `period`)	String	No

Detail of term.interestCalculateType: Possible values:

period: Interests are calculated and applied once at the beginning of the debt for the entire period. The total interest amount is determined at the start and distributed in the installments.
lifetime: Interests are calculated and applied continuously throughout the debt's lifetime. The calculation is done periodically (e.g., daily) on the outstanding balance.

Additional explanation:

With period, the borrower knows from the start the total interest amount they will pay, regardless of early payments.
With lifetime, the interest amount may vary if early payments are made, as it is recalculated on the outstanding balance. This interest calculation type is only supported for single-installment debts.

Notes:

Either clientId or externalId must be provided, but not both.
Either productId or terms must be provided, but not both.
If terms are not provided, the configured product values will be used.

Successful Response

The response includes a simulated Flow object.

Specific Errors

Error Code	Description
400	Invalid request. This can occur if required parameters are missing or if the provided values are not valid.
404	Client not found. This occurs if the provided `clientId` or `externalId` does not correspond to any client in the system.
409	Conflict. This can occur if the proposed terms are not compatible with the product's configuration or segmentations see DPA Products.

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

Simulate an Advanced DPA Flow

Performs an advanced simulation of a DPA flow. This simulation returns an array of simulated Flow objects and corresponds to the simulation of a DPA flow with all applicable products, see DPA Products and see DPA Product Segmentations.

POST /v1/dpas/advanced/simulations

Input Parameters:

Parameter	Description	Type	Required
`amount`	Agreement amount	Object	Yes
`clientId`	Client ID	String	No
`externalId`	Client's external ID	String	No
`disbursementDate`	Disbursement date	String	No
`metadata`*	Additional metadata used to evaluate segmentation rules	Object	No

Note: The key of the metadata must match the key of the segmentation rules. If there is overlap between a key of the metadata and a value obtained from the client's borrower fields, the value of the borrower field will prevail.

Successful Response:

The response will be an array of simulated Flow objects (the flowId cannot be GET).

Initiate a DPA Flow

Initiates a new Deferred Payment Agreement flow with a product ID.

POST /v1/dpas

Request Body

{
  "amount": {
    "amount": "10000.00",
    "currency": "ARS"
  },
  "clientId": "e732bc5f-5b84-4a0a-81b4-5354d4625a8b",
  "externalId": "CLI-12345",
  "disbursementDate": "2023-04-15",
  "productId": "dd58d928-b836-494b-9f0c-05919f001791",
  "terms": {
    "amortizationType": "equal_total",
    "installments": 3,
    "repayEvery": 30,
    "interestRate": {
      "rate": "15.00",
      "period": 360
    },
    "interestTax": 21,
    "interestCalculateType": "period"
  }
}

Input Parameters

Parameter	Description	Type	Required
`amount`	Agreement amount	Object	Yes
`amount.amount`	Amount value	String	Yes
`amount.currency`	Amount currency	String	Yes
`clientId`	Client ID in the system	String (UUID)	No*
`externalId`	Client's external ID in the partner's system	String	No*
`disbursementDate`	Proposed disbursement date	String (YYYY-MM-DD)	No
`productId`	Credit product ID to use	String (UUID)	No*
`terms`	Proposed terms for the agreement	Object	No**
`terms.amortizationType`	Type of amortization	String ("flat" or "equal_total")	No
`terms.installments`	Number of installments	Integer	No
`terms.repayEvery`	Payment frequency in days	Integer	No
`terms.interestRate`	Interest rate configuration	Object	No
`terms.interestRate.rate`	Interest rate value	String	No
`terms.interestRate.period`	Interest rate period in days	Integer	No
`terms.interestTax`	Interest tax rate	Number	No
`terms.interestCalculateType`	Interest calculation type	String ("period" or "lifetime")	No

Note: Either clientId or externalId must be provided, but not both.
Note: Either productId or terms must be provided, but not both.
Note: If terms are not provided, the configured product values will be used.

Successful Response

The response includes a Flow object.

Specific Errors

Error Code	Description
400	Invalid request. This can occur if required parameters are missing or if the provided values are not valid.
404	Client not found. This occurs if the provided `clientId` or `externalId` does not correspond to any client in the system.
409	Conflict. This can occur if the proposed terms are not compatible with the product's configuration or segmentations see DPA Products.

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

Get a DPA Flow

Retrieves information about a specific DPA flow.

GET /v1/dpas/:flow_id

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow to retrieve

Successful Response:

The response will be a Flow object.

Approve a DPA Flow

Approves a DPA flow. After approval, the credit line is reserved for the final amount. Re-approving is allowed while no debt is yet confirmed — the reservation adjusts to the new amount/date.

PUT /v1/dpas/:flow_id/approval

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow to approve

Input Parameters:

Parameter	Description	Type	Required
`amount`	Final approved amount	Object (Money)	Yes
`disbursementDate`	Disbursement date	String (YYYY-MM-DD)	Yes
`externalId`	Client's external ID (or use `clientId`)	String	No*
`clientId`	Client ID (or use `externalId`)	String (UUID)	No*
`referenceId`	External reference (e.g., purchase order)	String	No

Either clientId or externalId must be provided, but not both.

Example Request:

{
    "externalId": "cli:123",
    "amount": { "amount": "10000.00", "currency": "ARS" },
    "disbursementDate": "2023-04-15",
    "referenceId": "PO-1234"
}

Successful Response:

The response will be an updated Flow object. Note: the returned status is often approval-started while the credit-line reservation settles asynchronously. Poll GET /v1/dpas/:flow_id to see it transition to approved.

Cancel a DPA Flow

Cancels a DPA flow.

PUT /v1/dpas/:flow_id/cancellation

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow to cancel

Input Parameters:

Parameter	Description	Type	Required
`reason`	Reason for cancellation	String	No

Successful Response:

The response will be an updated Flow object.

Close a DPA Flow

Closes a DPA flow, indicating that no more invoices will be added.

PUT /v1/dpas/:flow_id/closure

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow to close

Successful Response:

The response will be an updated Flow object.

The Invoice Object

The Invoice object represents an invoice associated with a DPA flow in the system.

{
    "referenceId": "INV-1234",
    "invoiceDate": "2023-09-22",
    "amount": {
        "amount": "50000.00",
        "currency": "ARS"
    },
    "subTotalAmount": {
        "amount": "41322.31",
        "currency": "ARS"
    },
    "installments": [
        {
            "amount": {
                "amount": "25000.00",
                "currency": "ARS"
            },
            "interest": {
                "amount": "1250.00",
                "currency": "ARS"
            },
            "tax": {
                "amount": "262.50",
                "currency": "ARS"
            },
            "dueDate": "2023-10-22"
        },
        {
            "amount": {
                "amount": "25000.00",
                "currency": "ARS"
            },
            "interest": {
                "amount": "1250.00",
                "currency": "ARS"
            },
            "tax": {
                "amount": "262.50",
                "currency": "ARS"
            },
            "dueDate": "2023-11-22"
        }
    ],
    "notes": "Invoice for PO-1234",
    "debtId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4"
}

Attributes

Attribute	Description	Type
`referenceId`	Unique identifier of the invoice	String
`invoiceDate`	Invoice issue date	String (ISO 8601)
`amount`	Total invoice amount	Object
`subTotalAmount`	Invoice subtotal amount (optional)	Object
`installments`	Invoice payment plan	Array of Object
`notes`	Additional notes about the invoice (optional)	String
`debtId`	Identifier of the associated debt (optional)	String

Installment Object

Attribute	Description	Type
`amount`	Installment amount	Object
`interest`	Installment interest amount	Object
`tax`	Installment tax amount	Object
`dueDate`	Installment due date	String (ISO 8601)

Add Invoice to a DPA Flow

Adds an invoice to a DPA flow and confirms it.

POST /v1/dpas/:flow_id/invoices

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow

Input Parameters:

Parameter	Description	Type	Required
`referenceId`	Invoice reference ID	String	Yes
`invoiceDate`	Invoice date	String	Yes
`amount`	Total invoice amount	Object	Yes
`subTotalAmount`	Invoice subtotal amount	Object	No
`installments`	Invoice payment plan	Array	No
`notes`	Additional notes	String	No

Example Request:

{
    "referenceId": "INV-1234",
    "invoiceDate": "2023-09-22",
    "amount": {
        "amount": "50000.00",
        "currency": "ARS"
    },
    "subTotalAmount": {
        "amount": "41322.31",
        "currency": "ARS"
    },
    "installments": [
        {
            "amount": {
                "amount": "25000.00",
                "currency": "ARS"
            },
            "interest": {
                "amount": "1250.00",
                "currency": "ARS"
            },
            "tax": {
                "amount": "262.50",
                "currency": "ARS"
            },
            "dueDate": "2023-10-22"
        },
        {
            "amount": {
                "amount": "25000.00",
                "currency": "ARS"
            },
            "interest": {
                "amount": "1250.00",
                "currency": "ARS"
            },
            "tax": {
                "amount": "262.50",
                "currency": "ARS"
            },
            "dueDate": "2023-11-22"
        }
    ],
    "notes": "Invoice for PO-1234"
}

Successful Response:

The response will be a created Invoice object, including the generated debtId.

Get Invoices Associated with a DPA Flow

Retrieves the list of invoices associated with a specific DPA flow.

GET /v1/dpas/:flow_id/invoices

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow

Successful Response:

The response will be a list of Invoice objects related to the DPA flow.

Reopen a Canceled DPA Flow

Reopens a DPA flow that has been canceled due to expiration.

PUT /v1/dpas/:flow_id/reopen

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow to reopen

Input Parameters:

Parameter	Description	Type	Required
`expirationAt`	New expiration date	String	Yes
`reason`	Reason for reopening the flow	String	Yes

Example Request:

{
    "expirationAt": "2024-06-26",
    "reason": "Invoices pending to process for this flow"
}

Successful Response:

The response will be an updated Flow object.

The Flow Event Object

The Flow Event object represents an event that occurs in relation to a DPA flow in the system.

{
    "type": "flow-created",
    "timestamp": "2021-01-01T00:00:00Z",
    "aggregateType": "flow",
    "aggregateId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4",
    "data": {
        "flowId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4",
        "status": "pending",
        "amount": {
            "amount": "100000.00",
            "currency": "ARS"
        }
    },
    "metadata": {...}
}

Attributes

Attribute	Description	Type
`type`	Event type	String
`timestamp`	Date and time the event occurred	String (ISO 8601)
`aggregateType`	Type of aggregate the event belongs to	String
`aggregateId`	Unique identifier of the aggregate	String
`data`	Specific event data	Object
`metadata`	Additional event metadata	Object

Get Events of a DPA Flow

Retrieves the list of events associated with a specific DPA flow.

GET /v1/dpas/:flow_id/events

Path Parameters:

Parameter	Description
`flow_id`	ID of the DPA flow

Successful Response:

The response will be a list of Event objects related to the DPA flow.

Example Response:

[
    {
        "type": "flow-created",
        "timestamp": "2021-01-01T00:00:00Z",
        "aggregateType": "flow",
        "aggregateId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4",
        "data": {
            "flowId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4",
            "status": "pending",
            "amount": {
                "amount": "100000.00",
                "currency": "ARS"
            }
        },
        "metadata": {...}
    },
    {
        "type": "flow-approved",
        "timestamp": "2021-01-02T10:30:00Z",
        "aggregateType": "flow",
        "aggregateId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4",
        "data": {
            "flowId": "89480edc-d0e2-4e59-96ce-e705a3b6e1c4",
            "status": "approved"
        },
        "metadata": {
            "approvedBy": "user123"
        }
    }
]

This response provides a history of events related to the DPA flow, allowing tracking of changes and actions performed on the flow over time.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page