Skip to content

Disbursement

Disbursement allows integrator to send funds to a beneficiary bank account or e-wallet using the payout options available under the integrator's account. This integration is used for remittance, supplier and vendor payment, payroll, and other fund transfers.

Since funds are sent out of the integrator's account, the transaction data must include the payment instructions and the transaction compliance information of the sender and beneficiary.

To initiate a disbursement transaction, send the following request header and body parameters via POST.

POST/disbursement

HEADER PARAMETERS

Content-Type optional
string
Default content type of the API.
Authorization required
string
Unique identifier of the integrator.

REQUEST BODY SCHEMA: application/json

payload required
string
Generated JSON Web Token (JWT) from transaction data signed with integrator's secret using HS256 algorithm.
  • Secret - issued key used for signing the payload data
  • Transaction Data - is a JSON-formatted data as shown below
{
   "data":{
      "customer":{
         "first_name":"Abel",
         "last_name":"Maclead",
         "billing_address":{
            "line1":"CAP Building",
            "line2":"Ayala Avenue",
            "city_municipality":"Makati",
            "zip":"1229",
            "state_province_region":"Metro Manila",
            "country_code":"PH"
         },
         "shipping_address":{
            "line1":"CAP Building",
            "line2":"Ayala Avenue",
            "city_municipality":"Makati",
            "zip":"1229",
            "state_province_region":"Metro Manila",
            "country_code":"PH"
         },
         "contact":{
            "email":"amaclead@domain.com",
            "mobile":"+639123456789"
         }
      },
      "payment":{
         "description":"Payout for a supplier",
         "amount":1000.50,
         "currency":"PHP",
         "option":"{generatedOptionKey}",
         "merchant_reference_id":"PAYOUT-100001_TEST",
         "other_references":[
            "REF1", "REF2"
         ]
      },
      "payment_instructions":{
         "beneficiary_account":"1234567890",
         "currency":"PHP",
         "bic":"{bankIdentifierCode}",
         "name":"Juan Dela Cruz",
         "address":"123 Main Street, Makati"
      },
      "route":{
         "callback_url":"https://tlpe.io/thankyou",
         "notify_user":true
      },
      "transaction_compliance":{
         "transaction_type":"C2C",
         "nature":"Remittances",
         "sender":{
            "name":{
               "prefix":"Mr.",
               "first_name":"Juan Manuel",
               "middle_name":"Isidro",
               "last_name":"Dela Cruz",
               "suffix":"Jr.",
               "business_name":"Juan Dela Cruz Enterprises"
            },
            "birth_date":"1990-01-01",
            "place_of_birth":"Metro Manila",
            "nationality":"Filipino",
            "nature_of_business_or_employment":"Employed",
            "contact":{
               "email":"juan.delacruz@domain.com",
               "phone":"(02) 123-4567",
               "mobile":"+639123456789"
            },
            "identification":{
               "identification_type":"Passport",
               "identification_number":"P1234567A",
               "issuing_authority":"DFA - Manila",
               "issue_date":"2020-01-01",
               "expiry_date":"2030-01-01"
            },
            "present_address":{
               "line1":"123 Main Street",
               "line2":"Subdivision",
               "city_municipality":"Makati",
               "zip":"1229",
               "state_province_region":"Metro Manila",
               "country_code":"PH"
            },
            "permanent_address":{
               "line1":"123 Main Street",
               "line2":"Subdivision",
               "city_municipality":"Makati",
               "zip":"1229",
               "state_province_region":"Metro Manila",
               "country_code":"PH"
            },
            "is_same_as_present_address":true,
            "source_of_funds":"Salary",
            "purpose":"Remittance to Family",
            "relationship_with_beneficiary":"Father"
         },
         "beneficiary":{
            "beneficiary_type":"C2C",
            "name":{
               "prefix":"Ms.",
               "first_name":"Maria",
               "middle_name":"Santos",
               "last_name":"Dela Cruz",
               "suffix":"",
               "business_name":""
            },
            "birth_date":"1995-05-05",
            "place_of_birth":"Metro Manila",
            "nationality":"Filipino",
            "nature_of_business_or_employment":"Student",
            "contact":{
               "email":"maria.delacruz@domain.com",
               "phone":"(02) 123-4567",
               "mobile":"+639123456780"
            },
            "present_address":{
               "line1":"123 Main Street",
               "line2":"Subdivision",
               "city_municipality":"Makati",
               "zip":"1229",
               "state_province_region":"Metro Manila",
               "country_code":"PH"
            },
            "permanent_address":{
               "line1":"123 Main Street",
               "line2":"Subdivision",
               "city_municipality":"Makati",
               "zip":"1229",
               "state_province_region":"Metro Manila",
               "country_code":"PH"
            },
            "is_same_as_present_address":true,
            "account":{
               "account_type":"Bank",
               "account_name":"Maria Dela Cruz",
               "account_number":"1234567890",
               "bank_name":"Bank of Juan",
               "branch_name":"Main Branch",
               "branch_address":"123 Main Street Makati City, Metro Manila, Philippines, 1229"
            }
         }
      },
      "time_offset":"+08:00",
      "customer_ip_address":"0.0.0.0"
   }
}

See API Reference > Disbursement Body Payload Data, JWT Payload Signing for a guided reference.

Custom parameters can be added depending on the acquirer or payment processor/brand being used in the request. Include custom_parameters object in the request body if supported.

"custom_parameters": {
    "custom_name_1": "custom value here",
    "custom_name_1": "custom value here"
},

For guidance, you may coordinate with your respective account manager if custom parameter is supported for your account.

For option parameter value, get the generated code from Disbursement Options endpoint response.

After the payment transaction, page will be redirected to the callback URL set in the payload where a URL parameter transaction_id will be appended.

Example:

https://tlpe.io/thankyou?transaction_id={transactionId}

RESPONSE BODY PARAMETERS

timestamp
string
Transaction timestamp.
status
string
HTTP status code.
message
string
HTTP status code message/description.
path
string
Endpoint path used for the transaction.
data
data
Contains transaction related response.
    transaction_id
string
Payment reference number of the transaction.
    status_code
string
API status code.
    status_description
string
API status code message/description.

Request Samples

curl
    -X POST "https://test-api.tlpe.io/disbursement" \
    -H "Content-Type: application/json" \
    -H "Authorization: {integratorToken}" \
    -d "{
        "payload": "{generatedJwtPayload}"
    }"

Response Samples

{
    "timestamp":"2020-07-14T09:29:03.806+0000",
    "status":200,
    "message":"Request processed successfully",
    "path":"/disbursement",
    "data":{
        "transaction_id":"{transactionId}",
        "status_code":"OK.13.10",
        "status_description":"Waiting for disbursement"
    }
}

{
    "timestamp":"2020-07-14T09:29:03.806+0000",
    "status":422,
    "error":"Unprocessable Entity",
    "message":"Request cannot be processed",
    "path":"/disbursement",
    "messages":{
        "payment.amount":["must not be blank"]
    }
}

See API Reference > Response Messages for a guided reference.