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 payment channel. Refer to the id from the response of the Get Channel List. Must be a channel whose provider supports saved payments, otherwise the request fails with ChannelNotSupportPreAddPayment (2104).
The merchant-side unique order reference or invoice tracking sequence code.
Maximum string length:
50The customer's IP address captured by the merchant server.
Maximum string length:
50The synchronous return URL where the customer's browser is automatically redirected after the transaction is completed.
Maximum string length:
500Example:
"https://returnurl.com/"
Currency code with a 3-letter ISO 4217 standard code (e.g., MYR).
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. See Callback Notifications for the payload and signature verification steps.
Maximum string length:
500Example:
"https://callback.com/"
Show child attributes
Show child attributes
Your unique Merchant ID assigned by CommercePay.
Numeric timestamp in milliseconds representing request validation freshness, generated via new Date().getTime(). Example: 1621851652617.
Example:
1621851652617