Goods & Services API documentation

Goods & Services API documentation
3. Variable value payments


Payment transactions with variable value

Using DT One Goods & Services API you can perform bill payments (e.g. bill payments for electricity services in Indonesia).

A payment transaction will pay in full the amount that is payable for the account id of the customer. Prior to the payment, a request to check the amount to pay must be made. Amounts to be paid are in local currency.

Depending on the parameters submitted to the API, a notification SMS may be sent to the sender and/or recipient of the transaction.

You can either do a real transaction, or simulate a transaction. A simulation will not debit your TShop account but will give you an overview of the response you would get from processing a real transaction.

Note that a successful status returned in the simulation does not guarantee a successful status during the real processing of the transaction. As no remote call is being performed during a simulation, exceptions that may happen between DT One and the partner delivering the final value to the recipient can not be anticipated and are therefore considered as successful.

If the transaction is processed successfully, the system will return a 201 http status. The status of the transaction itself is returned in the response.
If an error occurred during the processing, an HTTP code 400 or 500 will be returned.

1 - Retrieve the amount to pay

GET /product/variable_value_payments/{product_id}[?account_number=XXX]

Response :

HTTP Code: 200

Body:

{
    "account_currency": "MYR",
    "local_value": 62973,
    "local_currency": "IDR",
    "wholesale_price": 20.89,
    "retail_price": 20.89,
    "fee": 3,
    "payment": {
        "fee": 5000,
        "currency": "IDR",
        "amount": 57973,
        "name": "ABD KARIM"
    }
}

2 - Perform a PAYMENT transaction

Request :

POST /transactions/variable_value_payments

Transaction parameters :

Parameter Type Mandatory Description
account_number Text Yes Identifier of the payment to process (bill, …)
product_id Numeric Yes Product ID for the transaction, retrieve via product discovery methods
external_id Numeric Yes Unique ID of the transaction given by the client application
simulation Boolean No 1: simulation mode , 0: real transaction, set to 1 (simulation) by default
sender_sms_notification Boolean No Whether a SMS has to be sent to the sender mobile
sender_sms_text Text No Custom message to send to the sender mobile, up to 30 characters
recipient_sms_notification Boolean No Whether a SMS has to be sent to the recipient mobile
recipient_sms_text Text No Custom message to send to the recipient mobile, up to 30 characters
sender.last_name Text No Last name of the sender
sender.middle_name Text No Middle name of the sender
sender.first_name Text No First name of the sender
sender.email Email No Email of the sender
sender.mobile Phone Yes Mobile of the sender
recipient.last_name Text No Last name of the recipient
recipient.middle_name Text No Middle name of the recipient
recipient.first_name Text No First name of the recipient
recipient.email Email No Email of the recipient
recipient.mobile Phone Yes Mobile of the recipient
custom_field_1 Text No Optional custom information field
custom_field_2 Text No Optional custom information field
custom_field_3 Text No Optional custom information field

Body:

{
  "account_number":"123123123123",
  "product_id":"159",
  "external_id":"14248512386098430",
  "simulation":"0",
  "sender_sms_notification":"1",
  "sender_sms_text":"Sender message",
  "recipient_sms_notification":"1",
  "recipient_sms_text":"Recipient message",
  "sender":{
    "last_name":"Delorm",
    "middle_name":"",
    "first_name":"John",
    "email":"john@testaccount.com",
    "mobile":"6012345678"
  },
  "recipient":{
    "last_name":"Delorm",
    "middle_name":"",
    "first_name":"Lisa",
    "email":"lisa@testaccount.com",
    "mobile":"6012234345"
  }
}

Response :

HTTP Code: 201

Body:

{
    "transaction_id": "215278",
    "simulation": 0,
    "status": "0",
    "status_message": "Transaction successful",
    "date": "2016-06-09 05:16:29",
    "account_number": "123123123123",
    "external_id": "14248512386098430",
    "operator_reference": "10290928",
    "product_id": "159",
    "product": "PLN postpaid",
    "product_desc": "PLN postpaid",
    "product_currency": "IDR",
    "product_value": 62973,
    "local_currency": "IDR",
    "local_value": 62973,
    "operator_id": "1671",
    "operator": "PLN Indonesia",
    "country_id": "767",
    "country": "Indonesia",
    "account_currency": "MYR",
    "wholesale_price": 20.89,
    "retail_price": 20.89,
    "fee": 3,
    "payment": {
        "amount": 57973,
        "currency": "IDR",
        "fee": 5000,
        "name": "ABD KARIM"
    },
    "sender": {
        "last_name": "Delorm",
        "middle_name": "",
        "first_name": "John",
        "email": "john@testaccount.com",
        "mobile": "6012345678",
        "custom_field_1": "",
        "custom_field_2": "",
        "custom_field_3": ""
    },
    "recipient": {
        "last_name": "Delorm",
        "middle_name": "",
        "first_name": "Lisa",
        "email": "lisa@testaccount.com",
        "mobile": "6012234345",
        "custom_field_1": "",
        "custom_field_2": "",
        "custom_field_3": ""
    },
    "sender_sms_notification": 1,
    "sender_sms_text": "Sender message",
    "recipient_sms_notification": 1,
    "recipient_sms_text": "Recipient message",
    "custom_field_1": "",
    "custom_field_2": "",
    "custom_field_3": ""
}

3 - Retrieve a PAYMENT transaction

Requests :

GET /transactions/variable_value_payments/{payment_id} - Retrieve the details of the transaction based on the DT One identifier. The response is in the same format as the POST response.

GET /transactions/variable_value_payments/ext-{external-id} - Retrieve the details of the transaction based on the external identifier. The response is in the same format as the POST response.