Add Saved Payment
curl --request POST \
--url https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment \
--header 'Abp-TenantId: <abp-tenantid>' \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json-patch+json' \
--header 'cap-signature: <cap-signature>' \
--data '
{
"channelId": 123,
"referenceCode": "<string>",
"ipAddress": "<string>",
"returnUrl": "https://returnurl.com/",
"currencyCode": "MYR",
"userAgent": "<string>",
"callbackUrl": "https://callback.com/",
"customer": {
"email": "email@gmail.com",
"mobileNo": "0123456789",
"name": "name",
"username": "username",
"identificationNumber": "<string>"
},
"tenantId": 123,
"timestamp": 1621851652617
}
'import requests
url = "https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment"
payload = {
"channelId": 123,
"referenceCode": "<string>",
"ipAddress": "<string>",
"returnUrl": "https://returnurl.com/",
"currencyCode": "MYR",
"userAgent": "<string>",
"callbackUrl": "https://callback.com/",
"customer": {
"email": "email@gmail.com",
"mobileNo": "0123456789",
"name": "name",
"username": "username",
"identificationNumber": "<string>"
},
"tenantId": 123,
"timestamp": 1621851652617
}
headers = {
"Abp-TenantId": "<abp-tenantid>",
"Authorization": "<authorization>",
"cap-signature": "<cap-signature>",
"Content-Type": "application/json-patch+json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Abp-TenantId': '<abp-tenantid>',
Authorization: '<authorization>',
'cap-signature': '<cap-signature>',
'Content-Type': 'application/json-patch+json'
},
body: JSON.stringify({
channelId: 123,
referenceCode: '<string>',
ipAddress: '<string>',
returnUrl: 'https://returnurl.com/',
currencyCode: 'MYR',
userAgent: '<string>',
callbackUrl: 'https://callback.com/',
customer: {
email: 'email@gmail.com',
mobileNo: '0123456789',
name: 'name',
username: 'username',
identificationNumber: '<string>'
},
tenantId: 123,
timestamp: 1621851652617
})
};
fetch('https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'channelId' => 123,
'referenceCode' => '<string>',
'ipAddress' => '<string>',
'returnUrl' => 'https://returnurl.com/',
'currencyCode' => 'MYR',
'userAgent' => '<string>',
'callbackUrl' => 'https://callback.com/',
'customer' => [
'email' => 'email@gmail.com',
'mobileNo' => '0123456789',
'name' => 'name',
'username' => 'username',
'identificationNumber' => '<string>'
],
'tenantId' => 123,
'timestamp' => 1621851652617
]),
CURLOPT_HTTPHEADER => [
"Abp-TenantId: <abp-tenantid>",
"Authorization: <authorization>",
"Content-Type: application/json-patch+json",
"cap-signature: <cap-signature>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment"
payload := strings.NewReader("{\n \"channelId\": 123,\n \"referenceCode\": \"<string>\",\n \"ipAddress\": \"<string>\",\n \"returnUrl\": \"https://returnurl.com/\",\n \"currencyCode\": \"MYR\",\n \"userAgent\": \"<string>\",\n \"callbackUrl\": \"https://callback.com/\",\n \"customer\": {\n \"email\": \"email@gmail.com\",\n \"mobileNo\": \"0123456789\",\n \"name\": \"name\",\n \"username\": \"username\",\n \"identificationNumber\": \"<string>\"\n },\n \"tenantId\": 123,\n \"timestamp\": 1621851652617\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Abp-TenantId", "<abp-tenantid>")
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("cap-signature", "<cap-signature>")
req.Header.Add("Content-Type", "application/json-patch+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment")
.header("Abp-TenantId", "<abp-tenantid>")
.header("Authorization", "<authorization>")
.header("cap-signature", "<cap-signature>")
.header("Content-Type", "application/json-patch+json")
.body("{\n \"channelId\": 123,\n \"referenceCode\": \"<string>\",\n \"ipAddress\": \"<string>\",\n \"returnUrl\": \"https://returnurl.com/\",\n \"currencyCode\": \"MYR\",\n \"userAgent\": \"<string>\",\n \"callbackUrl\": \"https://callback.com/\",\n \"customer\": {\n \"email\": \"email@gmail.com\",\n \"mobileNo\": \"0123456789\",\n \"name\": \"name\",\n \"username\": \"username\",\n \"identificationNumber\": \"<string>\"\n },\n \"tenantId\": 123,\n \"timestamp\": 1621851652617\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Abp-TenantId"] = '<abp-tenantid>'
request["Authorization"] = '<authorization>'
request["cap-signature"] = '<cap-signature>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n \"channelId\": 123,\n \"referenceCode\": \"<string>\",\n \"ipAddress\": \"<string>\",\n \"returnUrl\": \"https://returnurl.com/\",\n \"currencyCode\": \"MYR\",\n \"userAgent\": \"<string>\",\n \"callbackUrl\": \"https://callback.com/\",\n \"customer\": {\n \"email\": \"email@gmail.com\",\n \"mobileNo\": \"0123456789\",\n \"name\": \"name\",\n \"username\": \"username\",\n \"identificationNumber\": \"<string>\"\n },\n \"tenantId\": 123,\n \"timestamp\": 1621851652617\n}"
response = http.request(request)
puts response.read_body{
"transactionNumber": "<string>",
"redirectUrl": "<string>"
}{
"code": 2103,
"message": "This customer already has a saved payment method on this channel."
}Saved Payment APIs
Add Saved Payment
Pre add customer payer payment details in Payment Gateway
Allow merchants save their customer payment details and using their system generated Unique Id to identify each of customers.
- Merchants shall pass their customers Unique Id to “customer.username” parameter
- Merchants may get customers saved payment details by using Check Saved Payment
- Channel Id may refer to the Get Channel List
POST
/
api
/
services
/
app
/
PaymentGateway
/
AddSavePayment
Add Saved Payment
curl --request POST \
--url https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment \
--header 'Abp-TenantId: <abp-tenantid>' \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json-patch+json' \
--header 'cap-signature: <cap-signature>' \
--data '
{
"channelId": 123,
"referenceCode": "<string>",
"ipAddress": "<string>",
"returnUrl": "https://returnurl.com/",
"currencyCode": "MYR",
"userAgent": "<string>",
"callbackUrl": "https://callback.com/",
"customer": {
"email": "email@gmail.com",
"mobileNo": "0123456789",
"name": "name",
"username": "username",
"identificationNumber": "<string>"
},
"tenantId": 123,
"timestamp": 1621851652617
}
'import requests
url = "https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment"
payload = {
"channelId": 123,
"referenceCode": "<string>",
"ipAddress": "<string>",
"returnUrl": "https://returnurl.com/",
"currencyCode": "MYR",
"userAgent": "<string>",
"callbackUrl": "https://callback.com/",
"customer": {
"email": "email@gmail.com",
"mobileNo": "0123456789",
"name": "name",
"username": "username",
"identificationNumber": "<string>"
},
"tenantId": 123,
"timestamp": 1621851652617
}
headers = {
"Abp-TenantId": "<abp-tenantid>",
"Authorization": "<authorization>",
"cap-signature": "<cap-signature>",
"Content-Type": "application/json-patch+json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Abp-TenantId': '<abp-tenantid>',
Authorization: '<authorization>',
'cap-signature': '<cap-signature>',
'Content-Type': 'application/json-patch+json'
},
body: JSON.stringify({
channelId: 123,
referenceCode: '<string>',
ipAddress: '<string>',
returnUrl: 'https://returnurl.com/',
currencyCode: 'MYR',
userAgent: '<string>',
callbackUrl: 'https://callback.com/',
customer: {
email: 'email@gmail.com',
mobileNo: '0123456789',
name: 'name',
username: 'username',
identificationNumber: '<string>'
},
tenantId: 123,
timestamp: 1621851652617
})
};
fetch('https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'channelId' => 123,
'referenceCode' => '<string>',
'ipAddress' => '<string>',
'returnUrl' => 'https://returnurl.com/',
'currencyCode' => 'MYR',
'userAgent' => '<string>',
'callbackUrl' => 'https://callback.com/',
'customer' => [
'email' => 'email@gmail.com',
'mobileNo' => '0123456789',
'name' => 'name',
'username' => 'username',
'identificationNumber' => '<string>'
],
'tenantId' => 123,
'timestamp' => 1621851652617
]),
CURLOPT_HTTPHEADER => [
"Abp-TenantId: <abp-tenantid>",
"Authorization: <authorization>",
"Content-Type: application/json-patch+json",
"cap-signature: <cap-signature>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment"
payload := strings.NewReader("{\n \"channelId\": 123,\n \"referenceCode\": \"<string>\",\n \"ipAddress\": \"<string>\",\n \"returnUrl\": \"https://returnurl.com/\",\n \"currencyCode\": \"MYR\",\n \"userAgent\": \"<string>\",\n \"callbackUrl\": \"https://callback.com/\",\n \"customer\": {\n \"email\": \"email@gmail.com\",\n \"mobileNo\": \"0123456789\",\n \"name\": \"name\",\n \"username\": \"username\",\n \"identificationNumber\": \"<string>\"\n },\n \"tenantId\": 123,\n \"timestamp\": 1621851652617\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Abp-TenantId", "<abp-tenantid>")
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("cap-signature", "<cap-signature>")
req.Header.Add("Content-Type", "application/json-patch+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment")
.header("Abp-TenantId", "<abp-tenantid>")
.header("Authorization", "<authorization>")
.header("cap-signature", "<cap-signature>")
.header("Content-Type", "application/json-patch+json")
.body("{\n \"channelId\": 123,\n \"referenceCode\": \"<string>\",\n \"ipAddress\": \"<string>\",\n \"returnUrl\": \"https://returnurl.com/\",\n \"currencyCode\": \"MYR\",\n \"userAgent\": \"<string>\",\n \"callbackUrl\": \"https://callback.com/\",\n \"customer\": {\n \"email\": \"email@gmail.com\",\n \"mobileNo\": \"0123456789\",\n \"name\": \"name\",\n \"username\": \"username\",\n \"identificationNumber\": \"<string>\"\n },\n \"tenantId\": 123,\n \"timestamp\": 1621851652617\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://staging-payments.commerce.asia/api/services/app/PaymentGateway/AddSavePayment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Abp-TenantId"] = '<abp-tenantid>'
request["Authorization"] = '<authorization>'
request["cap-signature"] = '<cap-signature>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n \"channelId\": 123,\n \"referenceCode\": \"<string>\",\n \"ipAddress\": \"<string>\",\n \"returnUrl\": \"https://returnurl.com/\",\n \"currencyCode\": \"MYR\",\n \"userAgent\": \"<string>\",\n \"callbackUrl\": \"https://callback.com/\",\n \"customer\": {\n \"email\": \"email@gmail.com\",\n \"mobileNo\": \"0123456789\",\n \"name\": \"name\",\n \"username\": \"username\",\n \"identificationNumber\": \"<string>\"\n },\n \"tenantId\": 123,\n \"timestamp\": 1621851652617\n}"
response = http.request(request)
puts response.read_body{
"transactionNumber": "<string>",
"redirectUrl": "<string>"
}{
"code": 2103,
"message": "This customer already has a saved payment method on this channel."
}This call places a real MYR 1.00 verification transaction. CommercePay charges the customer’s payment method MYR 1.00 through the provider to verify the card/wallet is valid, then automatically refunds it once the save completes. Expect the normal payment callback/webhook activity for this verification transaction — no separate refund call is needed on your side.
One saved payment per customer per channel. If
customer.username already has a saved payment method on the given channelId, this call fails with UserIsSavedPayment (2103) instead of replacing it. To save a new payment method for that customer/channel, first revoke the existing one via Revoke Saved Payment.Errors
In addition to standard signature errors, this endpoint can return:| Code | Name | Meaning |
|---|---|---|
| 2001 | InvalidChannel | channelId does not match an existing channel. |
| 2102 | UsernameIsRequired | customer.username was not supplied. |
| 2103 | UserIsSavedPayment | This customer already has a saved payment method on this channel. |
| 2104 | ChannelNotSupportPreAddPayment | The channel’s provider does not support saving payment methods. |
Headers
Your unique Merchant ID assigned by CommercePay.
Your API credentials used for authentication (typically a Bearer token).
A unique security hash used to verify the integrity of the request body. See Generate Signature for how to generate this.
Body
application/json-patch+jsonapplication/jsontext/jsonapplication/*+json
An identifier that represents a CommercePay payments channel. Refer id on response end points Get Channel List. Must be a channel whose provider supports saved payments, otherwise the request fails with ChannelNotSupportPreAddPayment (2104).
Merchant Reference Code
Maximum string length:
50Customer’s IP address captured by the merchant system
Maximum string length:
50Return URL supplied by the merchant server for the payment response and used by CommercePay to redirect the customer's browser back to the desired page on the Merchant’s site
Maximum string length:
500Example:
"https://returnurl.com/"
Currency code with a 3-letter ISO 4217 standard code.
Example:
"MYR"
[Conditional] Customer’s user agent. It is recommended to input for a better user experience for specific channels due to different platforms such as desktop, mobile, or app view. Example channels impact: ShopeePay
Maximum string length:
200Callback URL is host-to-host communication. CommercePay sends the transaction response to the merchant callback server based on the callback URL given, including for the automatic MYR 1.00 verification charge and its refund. If the URL is provided, the callback will be triggered; otherwise, it would not trigger. Refer to the Merchant Callback URL to know more
Maximum string length:
500Example:
"https://callback.com/"
Show child attributes
Show child attributes
Fill in provided Tenant Id.
new Date().getTime()
Example:
1621851652617