NAV
shell php

Introduction

Welcome to the Smartpay v2 API! You can use our API to access Smartpay API endpoints, which will allow you to accept payments, manage your Smartpay wallet and process disbursements.

We have language bindings in Shell and PHP. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

API URL's

Authentication

Add the Authorization: Bearer YOUR_SECRET_KEY header to your requests

$curl = curl_init('API_ENDPOINT_HERE');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
curl_close($curl);

# With shell, you can just pass the correct header with each request
curl "API_ENDPOINT_HERE" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Make sure to replace YOUR_SECRET_KEY with your API secret_key.

Smartpay uses API secret_keys to allow access to the API. You can register at our merchant portal.

Smartpay expects for the API secret_key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR_SECRET_KEY

Payments

Get Payment Channels

$curl = curl_init('API_URL/channels');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
curl_close($curl);

curl "API_URL/channels" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The above command returns JSON structured like this:

{
    "success": true,
    "data": [
        {
            "type": "Wallet",
            "name": "QRPH"
        },
        {
            "type": "Wallet",
            "name": "GCash"
        },
        {
            "type": "Wallet",
            "name": "Maya"
        },
        {
            "type": "Card",
            "name": "Visa/Mastercard"
        }
    ],
    "message": "Avaialble channels found."
}

This endpoint retrieves available payment channels.

HTTP Request

GET API_URL/channels

Query Parameters

None

Make a Payment Collection request

$curl = curl_init('API_URL/paymentRequest');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, true);
$params = [
  "service_reference" => "P12345678",
  "amount" => "2499.99",
  "customer_email" => "tester@test.ph",
  "customer_mobile" => "",
  "customer_name" => "Tester",
  "description" => "Test transaction",
  "restrict_channels" => '["Card", "Wallet"]',
];
curl_setopt($curl, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($curl);
curl_close($curl);

curl "API_URL/paymentRequest" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_reference": "P12345678", "amount": "2499.99", "customer_email": "tester@test.ph", "customer_name": "Tester", "description": "Test transaction", "restrict_channels": '["Card", "Wallet"]'}' \
  -X POST

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "reference_number": "100000002",
        "amount": "2499.99",
        "customer_name": "Tester",
        "customer_email": "tester@test.ph",
        "customer_mobile": "",
        "service_reference": "P12345678",
        "description": "Test transaction"
    },
    "message": "Payment request created."
}

This endpoint allows you to generate a payment collection request.

HTTP Request

POST API_URL/paymentRequest

Form/Body Parameters

Parameter Required Description
service_reference Optional A reference defined by the merchant service to identify the transaction ex T000123456
amount Yes Amount to collect from the customer ex 2599.99
customer_email Yes Email address of the customer ex tester@test.ph
customer_mobile Optional Mobile number of the customer in 10 digit format ex 9271234567
customer_name Yes Name of the customer
description Yes Description of the payment transaction
restrict_channels Optional Set the list of channel types that will be available to the customer (Can be queried via the GET channels endpoint). Possible values are Card, Wallet, Over the Counter and Bank. Parameter shoud be passed as an array of strings

Get Payment Details

$params = [
  "service_reference" => "P12345678"
];
$curl = curl_init('API_URL/payments' . '?' . http_build_query($params));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
curl_close($curl);

curl "API_URL/payments?service_reference=P12345678" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "reference_number": "100000002",
        "merchant_name": "Smartpay",
        "service_reference": "P12345678",
        "service_name": "Test Service",
        "customer_name": "Tester",
        "customer_email": "tester@test.ph",
        "customer_mobile": "",
        "payment_channel": "QRPH",
        "request_amount": 2499.99,
        "channel_fee": 74.97,
        "customer_fee": 49.98,
        "settlement_amount": 2425.02,
        "status": "success",
        "status_description": "Payment completed.",
        "created_at": "2025-01-07 14:14:26",
        "paid_at": "2025-01-07 14:17:35"
    },
    "message": "Transaction found."
}

This endpoint retrieves details of a payment.

HTTP Request

GET API_URL/payments

Query Parameters

Parameter Required Description
service_reference Conditional A reference defined by the merchant service to identify the transaction (Required if reference_number is not passed)
reference_number Conditional The reference number returned by paymentRequest (Required if service_reference is not passed)

Delete a Payment Collection request

$curl = curl_init('API_URL/deletePaymentRequest');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, true);
$params = [
  "service_reference" => "P12345678"
];
curl_setopt($curl, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($curl);
curl_close($curl);

curl "API_URL/deletePaymentRequest" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_reference": "P12345678"}' \
  -X POST

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "reference_number": "100000002",
        "merchant_name": "Smartpay",
        "service_reference": "P12345678",
        "service_name": "Test Service",
        "customer_name": "Tester",
        "customer_email": "tester@test.ph",
        "customer_mobile": "",
        "payment_channel": "",
        "request_amount": 2499.99,
        "channel_fee": 0,
        "customer_fee": 0,
        "settlement_amount": 2499.99,
        "status": "cancelled",
        "status_description": "Payment request has been cancelled.",
        "created_at": "2025-01-08 11:28:44",
        "paid_at": "2025-01-08 11:28:58"
    },
    "message": "Transaction cancelled."
}

This endpoint allows you to cancel a payment collection request.

HTTP Request

POST API_URL/deletePaymentRequest

Form/Body Parameters

Parameter Required Description
service_reference Conditional A reference defined by the merchant service to identify the transaction (Required if reference_number is not passed)
reference_number Conditional The reference number returned by paymentRequest (Required if service_reference is not passed)

Payment Status Update via Webhook

Below is a sample funtion to validate the payload via the hash and your secret_key:

public function validate_hash($payload, $secret_key)
{
    $payload_hash = $payload['hash'];
    unset($payload['hash']);
    $for_hash = '';
    foreach ($payload as $p) {
        $for_hash .= $p;
    }
    return strcmp(hash_hmac('sha1', $for_hash, $secret_key, false), $payload_hash);
}

Refer to PHP Tab

The webhook contains the following json payload structure:

{
  "reference_number": "100000002",
  "merchant_name": "Smartpay",
  "service_reference": "P12345678",
  "service_name": "Test Service",
  "customer_name": "Tester",
  "customer_email": "tester@test.ph",
  "customer_mobile": "",
  "payment_channel": "",
  "request_amount": 2499.99,
  "channel_fee": 0,
  "customer_fee": 0,
  "settlement_amount": 2499.99,
  "status": "cancelled",
  "status_description": "Payment request has been cancelled.",
  "created_at": "2025-01-08 11:28:44",
  "paid_at": "2025-01-08 11:28:58",
  "hash": "ImRhdGEiOiB7CiAgICAgICAgInJlZmVyZW5jZV9udW1iZXIiOiAiMTAwMDAwMDAyIiwKICAgICAgICAibWVyY2hhbnRfbmFtZSI6ICJTbWFydHBheSIsCiAgICAgICAgInNlcnZpY2VfcmVmZXJlbmNlIjogIlAxMjM0NTY3OCIsCiAgICAgICAgInNlcnZpY2VfbmFtZSI6ICJUZXN0IFNlcnZp"
}

You can receive payment status updates via a webhook. The payload is sent via POST. Optionally you can validate the payload via the included hash.

You can set your webhook URL via our merchant portal.

HTTP Request

POST YOUR_WEBHOOK_URL

Disbursements

Get Disbursement Channels

$curl = curl_init('API_URL/disbursementChannels');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
curl_close($curl);

curl "API_URL/disbursementChannels" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The above command returns JSON structured like this:

{
    "success": true,
    "data": [
        {
            "channel": "InstaPay",
            "channel_id": 1,
            "name": "G-Xchange / GCash"
        },
        {
            "channel": "InstaPay",
            "channel_id": 2,
            "name": "Unionbank"
        },
        {
            "channel": "PesoNet",
            "channel_id": 3,
            "name": "BDO Unibank, Inc."
        },
    ],
    "message": "Avaialble channels found."
}

This endpoint retrieves available disbursement channels.

HTTP Request

GET API_URL/disbursementChannels

Query Parameters

None

Make a Disbursement request

$curl = curl_init('API_URL/disbursementRequest');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, true);
$params = [
  "service_reference" => "P12345678",
  "amount" => "2499.99",
  "channel_id" => 33,
  "account_email" => "tester@test.ph",
  "account_name" => "Juan Dela Cruz",
  "account_number" => "09458318180",
  "description" => "Test transaction",
];
curl_setopt($curl, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($curl);
curl_close($curl);

curl "API_URL/disbursementRequest" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_reference": "P12345678", "amount": "2499.99", "channel_id": 33, "account_email": "tester@test.ph", "account_name": "Juan Dela Cruz", "account_number": "09458318180", "description": "Test transaction"}' \
  -X POST

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "reference_number": "100000002",
        "amount": "2499.99",
        "disbursement_channel": "G-Xchange / GCash",
        "account_number": "09458318180",
        "account_name": "Juan Dela Cruz",
        "service_reference": "P12345678",
        "description": "Test transaction",
        "status": "pending"
    },
    "message": "Disbursement request created."
}

This endpoint allows you to generate a disbursement request.

HTTP Request

POST API_URL/disbursementRequest

Form/Body Parameters

Parameter Required Description
service_reference Optional A reference defined by the merchant service to identify the transaction ex T000123456
amount Yes Amount to collect from the customer ex 2599.99
channel_id Yes Channel ID from GET/disbursementChannels
account_email Yes Email address of the account to disburse to ex tester@test.ph
account_name Yes Account name to disburse to
account_number Yes Account number to disburse to
description Yes Description of the disbrusement transaction

Get Disbursement Details

$params = [
  "service_reference" => "P12345678"
];
$curl = curl_init('API_URL/disbursements' . '?' . http_build_query($params));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$headers[] = 'Authorization: Bearer YOUR_SECRET_KEY';
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($curl);
curl_close($curl);

curl "API_URL/disbursements?service_reference=P12345678" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "reference_number": "100000002",
        "merchant_name": "Smartpay",
        "service_name": "Test Service",
        "service_reference": "P12345678",
        "customer_email": "tester@test.ph",
        "account_name": "Juan Dela Cruz",
        "account_number": "09458318180",
        "disbursement_channel": "G-Xchange / GCash via InstaPay",
        "request_amount": 10,
        "channel_fee": 10,
        "disbursement_amount": 10,
        "status": "success",
        "status_description": "Disbursement completed.",
        "created_at": "2025-02-10 12:18:09",
        "disbursed_at": "2025-02-10 12:18:14"
    },
    "message": "Transaction fetched."
}

This endpoint retrieves details of a payment.

HTTP Request

GET API_URL/disbursements

Query Parameters

Parameter Required Description
service_reference Conditional A reference defined by the merchant service to identify the transaction (Required if reference_number is not passed)
reference_number Conditional The reference number returned by disbursementRequest (Required if service_reference is not passed)

Disbursement Status Update via Webhook

Below is a sample funtion to validate the payload via the hash and your secret_key:

public function validate_hash($payload, $secret_key)
{
    $payload_hash = $payload['hash'];
    unset($payload['hash']);
    $for_hash = '';
    foreach ($payload as $p) {
        $for_hash .= $p;
    }
    return strcmp(hash_hmac('sha1', $for_hash, $secret_key, false), $payload_hash);
}

Refer to PHP Tab

The webhook contains the following json payload structure:

{
  "reference_number": "100000002",
  "merchant_name": "Smartpay",
  "service_name": "Test Service",
  "service_reference": "P12345678",
  "account_email": "tester@test.ph",
  "account_name": "Juan Dela Cruz",
  "account_number": "09458318180",
  "disbursement_channel": "G-Xchange / GCash via InstaPay",
  "request_amount": 2499.99,
  "channel_fee": 0,
  "disbursement_amount": 2499.99,
  "status": "success",
  "status_description": "Disbursement completed.",  
  "created_at": "2025-01-08 11:28:44",
  "disbursed_at": "2025-01-08 11:28:58",
  "hash": "ImRhdGEiOiB7CiAgICAgICAgInJlZmVyZW5jZV9udW1iZXIiOiAiMTAwMDAwMDAyIiwKICAgICAgICAibWVyY2hhbnRfbmFtZSI6ICJTbWFydHBheSIsCiAgICAgICAgInNlcnZpY2VfcmVmZXJlbmNlIjogIlAxMjM0NTY3OCIsCiAgICAgICAgInNlcnZpY2VfbmFtZSI6ICJUZXN0IFNlcnZp"
}

You can receive disbursement status updates via a webhook. The payload is sent via POST. Optionally you can validate the payload via the included hash.

You can set your webhook URL via our merchant portal.

HTTP Request

POST YOUR_WEBHOOK_URL

Response Status Codes

The Smartpay API uses the following status codes:

Status Code Meaning
200 Successful -- Your request was successful.
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API secret_key is wrong.
402 Invalid Parameters -- Your request contains invalid parameters.
404 Not Found -- The specified endpoint/request could not be found.
405 Method Not Allowed -- You tried to access a endpoint with an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Payment Transaction Statuses

The Smartpay Payments API uses the following transaction statuses:

Status Description
open Payment request created
pending Pending payment from customer
success Payment has been completed by the customer
failed Customer has failed to complete the payment
expired Payment request has expired without successful payment
cancelled Payment request has been cancelled

Disbursement Transaction Statuses

The Smartpay Disbursements API uses the following transaction statuses:

Status Description
pending_approval Disbursement requires approval
rejected Disbursement request rejected
pending Disbursement is being processed
success Disbursement completed
failed Disbursement failed
expired Disbursement request has expired
cancelled Disbursement request has been cancelled

Sandbox Credit Cards

You can use the following test cards:

Card Brand Card Number Expiry Date Security Code
VISA 4111 1111 1111 1111 12/2028 123
Master Card 5555 5555 5555 4444 12/2028 123

Postman

You can download and import our Postman Environment and Collections below:

shell php