Gift Card: FIXED_VALUE_PIN

Product Type	Service (ID)	Subservice (ID)
FIXED_VALUE_PIN_PURCHASE	`GiftCard (4)`	`Retail Vouchers (41) or Gaming Vouchers (42) or Cash Cards Vouchers (43) or Food Vouchers (44) or Entertainment Vouchers (45) or Travel and Transport Vouchers (46)`

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

Example Product Retrieval

For full endpoint descriptions, see:

GET: Retrieve product by ID
GET: Retrieve list of products

GET /v1/products/28524

GET /v1/products?service_id=4&subservice_id=41

{
    "availability_zones": ["INTERNATIONAL"],
    "benefits": [
        {
            "additional_information": null,
            "amount": {
                "base": 10,
                "promotion_bonus": 0,
                "total_excluding_tax": 10,
                "total_including_tax": 10
            },
            "type": "CREDITS",
            "unit": "USD",
            "unit_type": "CURRENCY"
        }
    ],
    "description": "Amazon GiftCard USA 10 USD",
    "destination": {
        "amount": 10,
        "unit": "USD",
        "unit_type": "CURRENCY"
    },
    "id": 28524,
    "name": "Amazon GiftCard USA 10 USD",
    "operator": {
        "country": {
            "iso_code": "USA",
            "name": "United States",
            "regions": [
                {
                    "code": "USA",
                    "name": "United States"
                }
            ]
        },
        "id": 3285,
        "name": "Amazon USA",
        "regions": null
    },
    "pin": {
        "terms": "Restrictions apply, see amazon.com/gc-legal",
        "usage_info": [
            "To redeem your gift card visit http://www.amazon.com/redeem"
        ],
        "validity": {
            "quantity": -1,
            "unit": "DAY"
        }
    },
    "prices": {
        "retail": {
            "amount": 11.33,
            "fee": 0,
            "unit": "USD",
            "unit_type": "CURRENCY"
        },
        "wholesale": {
            "amount": 10.11,
            "fee": 0,
            "unit": "USD",
            "unit_type": "CURRENCY"
        }
    },
    "type": "FIXED_VALUE_PIN_PURCHASE",
    "validity": {
        "quantity": -1,
        "unit": "DAY"
    }
}

Required Fields - Pay Close Attention

The "required_*" fields indicate the additional data elements beyond the standard minimum payload that you must include in POST transaction requests for each corresponding party or identifier. These fields specify the necessary information for a particular product. If a field is listed as required, your transaction request will likely be unsuccessful if it is not included.

❗️
Warning
The example shown is for a particular product type delivered by a specific operator. Always, always check the "required_*" configuration for the exact product and operator you are integrating with. When the value of a "required_*" field is null, it means that no additional fields are necessary for that specific section beyond the base requirements for this product. Don't assume based on this one provided example that the field or fields listed are the only possibilities!


{
  "required_additional_identifier_fields": null,
  "required_beneficiary_fields": null,
  "required_credit_party_identifier_fields": [
    [
      "mobile_number"
    ]
  ],
  "required_debit_party_identifier_fields": null,
  "required_sender_fields": null,
  "required_statement_identifier_fields": null
}

{
  // ... other necessary fields from the minimum payload ...
  "credit_party_identifier": {
    "mobile_number": "+639173143100"
  },
  // ... other fields ...
}

Additional Fields for PIN-based Products

Most PIN-based products do not require additional fields beyond the standard minimum payload, as a PIN code for redemption is provided. Therefore, fields such as credit_party_identifier.mobile_number are typically not mandatory.

However, if you include the credit_party_identifier.mobile_number in your request for a PIN-based product, the PIN code will also be delivered via SMS to the provided mobile number.

When purchasing a PIN product, the discovery process will include a new "pin" field. This field contains the following information:

"pin": {
    "terms": "Restrictions apply, see amazon.com/gc-legal",
    "usage_info": [
        "To redeem your gift card visit http://www.amazon.com/redeem"
    ],
    "validity": {
        "quantity": -1,
        "unit": "DAY"
    }
}

terms: Any restrictions or legal terms associated with the PIN.
usage_info: Instructions on how to redeem the PIN.
validity: The validity period of the PIN, if applicable.

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

To post a transaction, you use the POST: Create a transaction asynchronously endpoint.

Implementation Techniques

Technique 1: One-Step Transaction

Create and confirm the transaction in one step.

{
    "external_id": "TEST-001",
    "product_id": 28524,
    "auto_confirm": true
}

Explanation: By setting auto_confirm to true, the transaction is created and confirmed immediately.

Technique 2: Two-Step Transaction

Create the transaction, then confirm it separately. When auto_confirm is set to false (or not specified):

A separate POST request to Confirm a transaction asynchronously is required.
This allows for a delay between transaction creation and submission to DT One, useful for:
- Collecting payment.
- Verifying RANGED product type prices.

Important:

The maximum time allowed between the CREATED (1) and CONFIRMED (2) statuses is 60 minutes.
Transactions not confirmed within 60 minutes will be automatically canceled.

{
    "external_id": "TEST-001",
    "product_id": 28524,
    "auto_confirm": false
}

Statuses for Transactions

A final status is a status after which there no further statuses.

Only COMPLETED 7, REJECTED 3, CANCELLED 4, and DECLINED 9 are final statuses. SUBMITTED 5 and CONFIRMED 2 are NOT final statuses.

---
config:
  theme: neutral
  fontSize: 16
  look: neo
  layout: fixed
---
flowchart LR
    B@{ label: "<b>CREATED</b><br><span style=\"font-size: 2em;\">1</span>" } -- "<span style=color:>POST<br>/transactions<br>/[id]<br>/confirm</span>" --> C@{ label: "<b>CONFIRMED</b><br><span style=\"font-size: 2em;\">2</span>" }
    C -- "<span style=color:>Sent to<br>receiving<br>partner</span>" --> D@{ label: "<b>SUBMITTED</b><br><span style=\"font-size: 2em;\">5</span>" }
    D --> E@{ label: "<b>COMPLETED</b><br><span style=\"font-size: 2em;\">7</span>" }
    E -- "<span style=color:>Callback</span>" --> F@{ label: "<b>REVERSED</b><br><span style=\"font-size: 2em;\">8</span>" }
    B -- "<span style=color:>Callback</span>" --> G@{ label: "<b>REJECTED</b><br><span style=\"font-size: 2em;\">3</span>" }
    B -- "<span style=color:>Callback<br>POST<br>/transactions<br>/[id]<br>/cancel</span>" --> H@{ label: "<b>CANCELLED</b><br><span style=\"font-size: 2em;\">4</span>" }
    D -- "<span style=color:>Callback</span>" --> I@{ label: "<b>DECLINED</b><br><span style=\"font-size: 2em;\">9</span>" }
    B@{ shape: rounded}
    C@{ shape: rounded}
    D@{ shape: rounded}
    E@{ shape: rounded}
    F@{ shape: rounded}
    G@{ shape: rounded}
    H@{ shape: rounded}
    I@{ shape: rounded}
    style B fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
    style C fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
    style D fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
    style E fill:#FFFFFF,color:#000,stroke:#90ee90,stroke-width:3px
    style F fill:#FFFFFF,stroke:black,stroke-width:3px
    style G fill:#FFFFFF,stroke:#f08080,stroke-width:3px
    style H fill:#FFFFFF,stroke:#f08080,stroke-width:3px
    style I fill:#FFFFFF,stroke:#f08080,stroke-width:3px

Final Status Descriptions

COMPLETED 7

The digital value service has been delivered. In rare cases, a successfully completed transaction can be reversed and assigned a REVERSED 8 status (so the definition for "Final Status" is applicable almost always.).

REJECTED 3

The transaction was unsuccessful on DT One’s side.

CANCELLED 4

The transaction was canceled by the initiator before confirmation.

DECLINED 9

The transaction was unsuccessful on the provider’s side.

Minimum Payload Request

{
    "external_id": "TEST-001",
    "product_id": 28524,
    "credit_party_identifier": {
        "mobile_number": "+639173143100"
    },
    "auto_confirm": true,
    "callback_url": "https://example.com/callback"
}

Field Descriptions:

Field Path	Description	Example
`external_id`	Unique ID per request generated from customer side.	`"TEST-001"`
`product_id`	ID of the product to be purchased.	`28524`
`credit_party_identifier.mobile_number`	Mobile number to be recharged.	`"+639173143100"`
`auto_confirm`	Specify if the transaction will be generated in one or two steps using the confirmation check.	`true`
`callback_url`	Callback URL or Webhook provided by the customer, we will send status updates to this URL.	`"https://example.com/callback"`

Response for POST: Create a Transaction Asynchronously

{
    "id": 2239238836,
    "external_id": "TEST-001",
    "status": {
        "id": 2,
        "message": "CONFIRMED",
        "class": {
            "id": 2,
            "message": "CONFIRMED"
        }
    },
    "creation_date": "2023-10-01T12:00:00Z",
    "confirmation_date": "2023-10-01T12:05:00Z",
    "callback_url": "https://example.com/callback",
    "product": {
        "id": 28524,
        "name": "Amazon GiftCard USA 10 USD",
        "type": "FIXED_VALUE_PIN_PURCHASE",
        "description": "Amazon GiftCard USA 10 USD"
    },
    "benefits": [
        {
            "type": "CREDITS",
            "amount": {
                "base": 10,
                "total_excluding_tax": 10,
                "total_including_tax": 10
            },
            "unit": "USD",
            "unit_type": "CURRENCY"
        }
    ],
    "prices": {
        "retail": {
            "amount": 11.33,
            "unit": "USD",
            "unit_type": "CURRENCY"
        },
        "wholesale": {
            "amount": 10.11,
            "unit": "USD",
            "unit_type": "CURRENCY"
        }
    }
}

Descriptions of Important Fields:

Field Path	Description	Example
`id`	Unique ID for the transaction generated by DT One.	`2239238836`
`external_id`	Unique ID for the transaction generated by the customer.	`"TEST-001"`
`status.id`	Status ID for the transaction.	`2`
`status.message`	Status message for the transaction.	`"CONFIRMED"`
`creation_date`	Date and time when the transaction was created.	`"2023-10-01T12:00:00Z"`
`confirmation_date`	Date and time when the transaction was confirmed.	`"2023-10-01T12:05:00Z"`
`callback_url`	URL provided by the customer to receive status updates.	`"https://example.com/callback"`
`product.id`	ID of the product associated with the transaction.	`28524`
`product.name`	Name of the product associated with the transaction.	`"Amazon GiftCard USA 10 USD"`
`benefits[].type`	Type of benefit provided by the transaction.	`"CREDITS"`
`benefits[].amount.base`	Base amount of the benefit.	`10`
`prices.retail.amount`	Retail price of the product.	`11.33`
`prices.wholesale.amount`	Wholesale price of the product.	`10.11`

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

Example Status Retrieval

Technique 1: Callback

Provide the callback_url (described in Step 2. Post Transactions) in the transaction request to receive asynchronous status updates.

Technique 2: Query the transaction using an ID

Use one of the following endpoints:

GET: Query a list of transactions

Can be used to look up the transaction using the External ID generated by the customer side (as well as to query a list).
GET: Query a transaction by ID

Look up the transaction using the Transaction ID that DT One generated.

Requests and Responses for "Get Final Status"

Query Using External ID

GET /v1/transactions?external_id=TEST-000005

Query Using Transaction ID

GET /v1/transactions/28524

Response for "Get Final Status"

{
    "id": 28524,
    "external_id": "TEST-000005",
    "status": {
        "id": 7,
        "message": "COMPLETED",
        "class": {
            "id": 7,
            "message": "COMPLETED"
        }
    },
    "creation_date": "2023-10-01T12:00:00Z",
    "confirmation_date": "2023-10-01T12:05:00Z",
    "callback_url": "https://example.com/callback",
    "product": {
        "id": 28524,
        "name": "Amazon GiftCard USA 10 USD",
        "type": "FIXED_VALUE_PIN_PURCHASE",
        "description": "Amazon GiftCard USA 10 USD"
    },
    "benefits": [
        {
            "type": "CREDITS",
            "amount": {
                "base": 10,
                "total_excluding_tax": 10,
                "total_including_tax": 10
            },
            "unit": "USD",
            "unit_type": "CURRENCY"
        }
    ],
    "prices": {
        "retail": {
            "amount": 11.33,
            "unit": "USD",
            "unit_type": "CURRENCY"
        },
        "wholesale": {
            "amount": 10.11,
            "unit": "USD",
            "unit_type": "CURRENCY"
        }
    }
}

Field Descriptions:

Field Path	Description	Example
`id`	Unique ID for the transaction generated by DT One.	`28524`
`external_id`	Unique ID for the transaction generated by the customer.	`"TEST-000005"`
`status.id`	Status ID for the transaction.	`7`
`status.message`	Status message for the transaction.	`"COMPLETED"`
`creation_date`	Date and time when the transaction was created.	`"2023-10-01T12:00:00Z"`
`confirmation_date`	Date and time when the transaction was confirmed.	`"2023-10-01T12:05:00Z"`
`callback_url`	URL provided by the customer to receive status updates.	`"https://example.com/callback"`
`product.id`	ID of the product associated with the transaction.	`28524`
`product.name`	Name of the product associated with the transaction.	`"Amazon GiftCard USA 10 USD"`
`benefits[].type`	Type of benefit provided by the transaction.	`"CREDITS"`
`benefits[].amount.base`	Base amount of the benefit.	`10`
`prices.retail.amount`	Retail price of the product.	`11.33`
`prices.wholesale.amount`	Wholesale price of the product.	`10.11`