Goods & Services API documentation

Goods & Services API documentation
1. Fixed value vouchers


Voucher transactions with fixed value

Using Goods & Services API you can perform voucher transactions (e.g.: used for grocery service).

A voucher transaction will typically return a voucher number and in some cases a PIN that may be needed by the final user to redeem the voucher.

Depending on the parameters submitted to the API, a notification SMS may be sent to the sender and/or recipient with the details 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 deivering 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 - Perform a VOUCHER transaction

Request:

POST /transactions/fixed_value_vouchers

Definition parameters to add:

Parameter Type Mandatory Description
account_number Text Yes Account number (or recipient phone number) the voucher has to be sent to
product_id Numeric Yes Product ID for the transaction, retrieved via the 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":"6281234567890",
  "product_id":"1",
  "external_id":"14248512386098429",
  "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":"6281234567890"
  }
}

Response :

HTTP Code: 201

Body:

{
  "transaction_id":"1778",
  "simulation":0,
  "status":"0",
  "status_message":"Transaction successful",
  "date":"2015-02-25 09:20:50",
  "account_number":"6281234567890",
  "external_id":"14248512386098429",
  "operator_reference":"",
  "product_id":"1",
  "product":"Voucher IDR 20000",
  "product_value":20000,
  "product_currency":"IDR",
  "local_value":20000,
  "local_currency":"IDR",
  "operator_id":"1988",
  "operator":"Indomaret VBE Indonesia",
  "country_id":"767",
  "country":"Indonesia",
  "account_currency":"USD",
  "wholesale_price":2.55,
  "retail_price":3,
  "fee":0,
  "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":"6281234567890",
    "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":"",
  "voucher":
  {
    "pin":"1111 2222 3333 4444",
    "pin2":"",
    "currency":"IDR",
    "value":"20000",
    "expiration_date":"2015-05-01",
    "info_1":"",
    "info_2":"",
    "info_3":""
  }
}

2 - Retrieve the details of a VOUCHER transaction

Requests:

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

GET /transactions/fixed_value_vouchers/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.