Key Considerations for Purchase Request Fields

When making a purchase request, it's important to determine which fields are required based on the product type and operator configuration. This is done by calling the Get Parameters method before performing the actual purchase.

🤔 Although the majority of prepaid products are mobile top-ups—making it seem like this step could be skipped—this isn't always the case. Therefore, we recommend being aware of this possibility and acting accordingly.

💡 Using the Get Parameters method ensures success and prevents future development needs in case of changes from providers by making your implementation resilient to changes.

🔍 How to Determine Required Fields

Before making a purchase, you should call the Get Parameters endpoint:

Endpoint:
GET /pre-paid/recharge/parameters/{terminalId}/{operatorId}

This method will return a list of parameters required for the given operator and terminal. The response indicates whether the product is dynamic (dynamic: true) and provides the list of required fields in the parameters array.

📌 Field Guidelines

`dynamicProductId`

Use only if the product is dynamic, as indicated by the dynamic: true flag in the Get Parameters response.

A product is dynamic if its details are obtained through the Get Products method.

If the product is not dynamic, leave this field empty or exclude it from the request.

`receiverEmail` and `documentNumber`

These fields are conditionally required, depending on the operator and product type.

They will appear in the parameters list from the Get Parameters response when required.

Always refer to this response to determine if receiverEmail or documentNumber must be included.

Standard Recharge Workflow (Non-Dynamic Products)

Purchase
Recharge Purchase

Dynamic Workflow (For Dynamic Products)

Get Products
Get Products

Purchase
Recharge Purchase

Make sure to always use the Get Parameters endpoint to verify which fields to send in your purchase request. This ensures compliance with operator-specific configurations and avoids unnecessary errors.

Request

Path Params

terminalId

integer <int32>

required

operatorId

integer <int32>

required

localReference

integer <int32>

required

Header Params

string

required

Default:

string

required

Default:

string

required

Default:

Body Params application/json

amountToSendX100

integer <int32> | null

required

(Required if used) Cannot be used together with destinationAmountX100.

destinationAmountX100

integer <int32> | null

required

(Required if used) Cannot be used together with amountToSendX100.

localDateTime

string <date-time>

required

account

string

required

dynamicProductId

string | null

optional

Only for dynamic workflow

receiverEmail

string | null

optional

documentNumber

string | null

optional

Example

{
    "amountToSendX100": 0,
    "destinationAmountX100": 0,
    "localDateTime": "2019-08-24T14:15:22Z",
    "account": "string",
    "dynamicProductId": "string",
    "receiverEmail": "string",
    "documentNumber": "string"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Body

integer <int32>

optional

items

array [object {6}]

optional

finalstatus

integer <int32>

optional

resultcode

string

optional

resultmessage

string

optional

supplierreference

string

optional

destinationcurrency

string

optional

destinationamount

number

optional

Example

{
    "rc": 0,
    "items": [
        {
            "finalstatus": 0,
            "resultcode": "10",
            "resultmessage": "OK",
            "supplierreference": "1234567890",
            "destinationcurrency": "DOP",
            "destinationamount": 1
        }
    ]
}

Purchase

Key Considerations for Purchase Request Fields#

🔍 How to Determine Required Fields#

📌 Field Guidelines#

dynamicProductId#

receiverEmail and documentNumber#

🚀 Related Workflows#

Standard Recharge Workflow (Non-Dynamic Products)#

Dynamic Workflow (For Dynamic Products)#

Request

Request samples

Responses

Key Considerations for Purchase Request Fields

🔍 How to Determine Required Fields

📌 Field Guidelines

`dynamicProductId`

`receiverEmail` and `documentNumber`

🚀 Related Workflows

Standard Recharge Workflow (Non-Dynamic Products)

Dynamic Workflow (For Dynamic Products)