Introduction Last updated: 2023-07-27
At Paymid Limited, we're dedicated to providing you with seamless consolidation of your payment stack and creating a great payment experience. Our API is designed to make integration effortless, enabling your customer to be redirected to our payment page without a hitch.
Don't hesitate to reach out with any questions or feedback.
Make Payment Request
Name: Payment Request
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName" : "John",
"middleName" : "", //optional
"lastName" : "Doe",
"reference" : "Test123456", //would be 10 characters and more and special characters not allowed
"dob" : "2023-07-20",
"email" : "[email protected]",
"contactNumber" : "+889943432",
"address" : "Sweden",
"country" : "Sweden",
"state" : "Blekinge", //If don't have any city, use "N/A" or "country_name"
"city" : "Jämshög",
"zipCode" : 11115,
"currency" : "USD", //ISO 4217 format
"amount" : 110,
"ttl" : 5, //optional (default value : 15 minutes)
"tagName" : "macbook pro m2", //optional
"merchantAccountId" : "100001",
"webhookUrl" : "https://example.webhook", //optional (if your Api Config already have ipn-url set &
if you send webhookUrl in the payload then it will be overwrite your config ipn & webhook url.)
"successUrl" : "https://example.com/success", //optional
"failedUrl" : "https://example.com/failed", //optional
}
N:B: If your country is missing from the list, please contact the help panel to activate.
Response Example
JSON
{
"success" : True,
"message" : "Payment Request Accepted",
"data" :{"payment_url" : "https://staging.centralisera.com/secure-payment/2bfec39f-55dc-4f48-976b-9d37b1675007"},
}
Make Payment Request with Checkout Template
Name: Payment Request
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
If you need to make payment with a specific template, then you need to provide the checkout templateId of the template .
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName" : "John",
"middleName" : "", //optional
"lastName" : "Doe",
"reference" : "Test123456", //would be 10 characters and more and special characters not allowed
"dob" : "2023-07-20",
"email" : "[email protected]",
"contactNumber" : "+889943432",
"address" : "Sweden",
"country" : "Sweden",
"state" : "Blekinge", //If don't have any city, use "N/A" or "country_name"
"city" : "Jämshög",
"zipCode" : 11115,
"currency" : "USD", //ISO 4217 format
"amount" : 110,
"ttl" : 5, //optional (default value : 15 minutes)
"tagName" : "macbook pro m2", //optional
"merchantAccountId" : "{{your_account_no}}",
"templateId" : {{checkout_template_id}},
"webhookUrl" : "https://example.webhook", //optional (if your Api Config already have ipn-url set &
if you send webhookUrl in the payload then it will be overwrite your config ipn & webhook url.)
}
N:B: If your country is missing from the list, please contact the help panel to activate.
Response Example
JSON
{
"success" : True,
"message" : "Payment Request Accepted",
"data" :{"payment_url" : "https://staging.centralisera.com/secure-payment/2bfec39f-55dc-4f48-976b-9d37b1675007"},
}
Dynamic Currency Payment By Cashier
Name: Dynamic Currency Payment
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
Description : If you need to convert currency to a different currency then you have to add another field depositCurrency which will be converted from the base currency. For example - if you deposit 100 USD to GBP then 79.45 GBP will be deposited
Authorization
Basic Auth
Username
Password
Body
Raw JSON
{
"firstName" : "John",
"middleName" : "", //optional
"lastName" : "Doe",
"reference" : "Test123456", //would be 10 characters and more and special characters not allowed
"dob" : "2023-07-20",
"email" : "[email protected]",
"contactNumber" : "+889943432",
"address" : "Sweden",
"country" : "Sweden",
"state" : "Blekinge", //If don't have any city, use "N/A" or "country_name"
"city" : "Jämshög",
"zipCode" : 11115,
"currency" : "USD", //ISO 4217 format
"depositCurrency" : "GBP", //optional - ISO 4217 format
"amount" : 110,
"ttl" : 5, //optional (default value : 15 minutes)
"tagName" : "macbook pro m2", //optional
"merchantAccountId" : "100001",
"webhookUrl" : "https://example.webhook", //optional (if your Api Config already have ipn-url set &
if you send webhookUrl in the payload then it will be overwrite your config ipn & webhook url.)
}
N:B: If your country is missing from the list, please contact the help panel to activate.
Response Example
JSON
{
"success" : True,
"message" : "Payment Request Accepted",
"data" :
{
"payment_url" : "https://staging.paymid.com/secure-payment/2bfec39f-55dc-4f48-976b-9d37b1675007"
},
}
See the attached image
Solutions List
Name: Get Available Payment Solutions
Method : GET
Url : {{BASE_URL}}/api/v1/merchant/active/solutions?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
Optional parameters:
includeGroups : 0 // default 0 or can be 1
isDepositEnabled : 1 // default 1 or can be 0
isPayoutEnabled : 1 // default 1 or can be 0
Response Example
JSON
{
"success": true,
"message": "Success",
"data": [
{
"id": "bf8ec435-d6ae-4ad3-83fe-61cf30b0dd6b",
"name": "ChargeMoney",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution/logo/Dchzw7xvWGyWi00abohJg9l60p2pdfTYAh5UuaUk.png",
"supported_currencies": [
"USD",
"EUR"
],
"regions": [],
"dynamic_currency_supported": 1
},
{
"id": "485093e0-2ed6-466a-8573-7ee659db40c5",
"name": "Trust Payments",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution/logo/08NXhGpSzOIq7kaTSz1m2s3fuQ27zaBYltnb9dqh.png",
"supported_currencies": [
"USD",
"EUR"
],
"regions": [
"Africa"
],
"dynamic_currency_supported": 0
},
{
"id": "5fb4b50a-9c9f-4acf-bd61-686ae557c118",
"name": "Ecommpay",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution/logo/nZQxdt4D3tZzSvFSpuye19LMlvyLcpSikmvjTr5E.jpg",
"supported_currencies": [
"USD",
"EUR"
],
"regions": [],
"dynamic_currency_supported": 1
},
{
"id": null,
"name": "Skrill",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution/logo/645c0d1281aab271.png",
"supported_currencies": [],
"regions": [],
"dynamic_currency_supported": 1
},
{
"id": "436f06e1-57ee-478d-bc9e-337ca4f2337f",
"name": "Paysafe Skrill",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution/logo/Ldpu3SX22Ua4lbHlb6ywynBwTIvzvnmdv2f2v6PO.jpg",
"supported_currencies": [
"USD",
"EUR"
],
"regions": [],
"dynamic_currency_supported": 1
}
]
}
Note: You can use the solution ID from this response in the Payment Request API to process payments through a specific solution.
Solution Groups List
Name: Get Active Payment Solution Groups
Method : GET
Url : {{BASE_URL}}/api/v1/merchant/active/solution-groups?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
Response Example
JSON
{
"success": true,
"message": "Merchant Solution Groups List",
"data": [
{
"id": "43ef5004-e4fd-4033-8ebd-d96f3d2f635a",
"name": "General Group",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution-groups/images/eHaDaILd2trXceSu0lSFhXfYhbWk55KbJwYvAcvs.png",
"type": "APM Group",
"payment_type": "APM Group",
"supported_currencies": [
"USD",
"INR"
],
"regions": [],
"dynamic_currency_supported": 0
},
{
"id": "e85c5d9c-84cc-11f0-9736-fc54af722c86",
"name": "VIP Group",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution-groups/images/uoHbODFyr7UpzS5eeTl1ob8kfhSPjJnO44t19Pvn.png",
"type": "APM Group",
"payment_type": "APM Group",
"supported_currencies": [
"USD",
"EUR"
],
"regions": [],
"dynamic_currency_supported": 0
},
{
"id": "e85c40be-84cc-11f0-9736-fc54af722c86",
"name": "New Group",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution-groups/images/OrUIVRKdsOSz2wi7Rjd48HGZ2VFjQ2Nz8YkjoA9G.png",
"type": "APM Group",
"payment_type": "APM Group",
"supported_currencies": [
"USD",
"EUR"
],
"regions": [],
"dynamic_currency_supported": 0
}
]
}
Note: You can use the Solution Group ID from this response in the Payment Request API as solutionGroupUuid to process payments through a specific solution group.
Payment Request with Solution ID
Name: Payment Request with Solution ID
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "John",
"middleName": "",
"lastName": "Doe",
"reference": "DuqXNBv0Q-sk-16",
"email": "[email protected]",
"dob": "1990-01-01",
"contactNumber": "+12345678",
"address": "SE",
"country": "Sweden",
"zipCode": "1212",
"currency": "USD",
"amount": "10.0",
"ttl": 5,
"tagName": "VIP Tag",
"webhookUrl": "{{webhookUrl}}",
"merchantAccountId": "{{your_account_no}}",
"solutionUniqueId": [
"485093e0-2ed6-466a-8573-7ee659db40c5"
],
}
Note: When using solutionId, the payment will be processed through the specified payment solution only. You can get the list of available solutions using the Solutions List API.
Response Example
JSON
{
"success" : true,
"message" : "Payment Request Accepted",
"data" :
{
"payment_url" : "https://staging.paymid.com/secure-payment/2bfec39f-55dc-4f48-976b-9d37b1675007"
},
}
Note: The above response contains a payment redirect URL which will redirect the customer to payment checkout page.
See the attached image
Payment Request with Solution Group UUID
Name: Payment Request with Solution Group UUID
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "John",
"middleName": "",
"lastName": "Doe",
"reference": "DuqXNBv0Q-sk-16",
"email": "[email protected]",
"dob": "1990-01-01",
"contactNumber": "+12345678",
"address": "SE",
"country": "Sweden",
"zipCode": "1212",
"currency": "USD",
"amount": "10.0",
"ttl": 5,
"tagName": "VIP Tag",
"webhookUrl": "{{webhookUrl}}",
"merchantAccountId": "{{your_account_no}}",
"solutionGroupUuid": "485093e0-2ed6-466a-8573-7ee659db40c5",
}
Note: When using solutionGroupUuid, the payment will be processed through the specified solution group only. You can get the list of available solution groups using the Solutions Groups List API.
Response Example
JSON
{
"success" : true,
"message" : "Payment Request Accepted",
"data" :
{
"payment_url" : "https://staging.paymid.com/secure-payment/2bfec39f-55dc-4f48-976b-9d37b1675007"
},
}
Note: The above response contains a payment redirect URL which will redirect the customer to payment checkout page.
See the attached image
Make Pre Auth Payment Request
Name: Payment Request (Pre Auth)
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName" : "John",
"middleName" : "", //optional
"lastName" : "Doe",
"reference" : "Test123456", //would be 10 characters and more and special characters not allowed
"dob" : "2023-07-20",
"email" : "[email protected]",
"contactNumber" : "+889943432",
"address" : "Sweden",
"country" : "Sweden",
"state" : "Blekinge", //If don't have any city, use "N/A" or "country_name"
"city" : "Jämshög",
"zipCode" : 11115,
"currency" : "USD", //ISO 4217 format
"amount" : 110,
"ttl" : 5, //optional (default value : 15 minutes)
"tagName" : "macbook pro m2", //optional
"merchantAccountId" : "100001",
"webhookUrl" : "https://example.webhook", //optional (if your Api Config already have ipn-url set &
if you send webhookUrl in the payload then it will be overwrite your config ipn & webhook url.),
"requestType" : "pre-auth", // (If this payment request is Pre Auth then pre-auth must be set as requestType value)
}
N:B: If your country is missing from the list, please contact the help panel to activate.
Response Example
JSON
{
"success" : True,
"message" : "Payment Request Accepted",
"data" :
{
"payment_url" : "https://staging.paymid.com/secure-payment/2bfec39f-55dc-4f48-976b-9d37b1675007"
"reference" : "DuqXNBv0Q-sk-151s2"
},
}
See the attached image
Capture Pre Auth Transaction
Name: Capture Transaction (Pre Auth)
Method : POST
Url : {{BASE_URL}}/api/v1/payment/capture-pre-auth-transaction
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"merchantAccountId" : "{{your_account_no}}",,
"reference" : "DuqXNBv0Q-sk-151s2",
}
Response
{
"success" : true ,
"message" : "Capture success" ,
"data" : []
}
AFT Payment Request
Name: Account Funding Transactions Payment Request
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
Description : Deposit account from Card
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "wx",
"middleName": "",
"lastName": "yz",
"reference": "XYOCJXEBF20",
"email": "[email protected]",
"dob": "1994-12-20",
"contactNumber": "01234567890",
"merchantAccountId": "100012",
"address": "Dhaka, Bangladesh",
"country": "Bangladesh",
"state": "Dhaka",
"city": "Dhaka",
"zipCode": "11115",
"currency": "USD",
"amount": "10",
"ttl": "10",
"tagName": "",
"solutionUniqueId": [
""
],
"additionalInfo": { // required for AFT payment
"aft": {
"accountNumber": "123456789",
"accountType": "ACCOUNT",
"customerCountryIso2a":"BD",
"customerFirstName":"John",
"customerLastName":"Danny"
}
},
"requestType": "aft" // required for AFT payment
}
Response
{
"success": true,
"message": "Payment Request Accepted",
"data": {
"payment_url": "https://sgw.paymid.com/secure-checkout/d02da6a7-c62e-4a13-b46a-35877fdb2597",
"reference": "XYOCJXEBF517",
"session_id": "d02da6a7-c62e-4a13-b46a-35877fdb2597"
}
}
Country List
Name: Get Country List
Method : GET
Url : {{BASE_URL}}/api/v1/country-list?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
Response Example
JSON
{
"success" : True,
"message" : "Country list",
"data" :[
{
"id": 213,
"name": "Sweden",
"emoji": "🇸🇪",
"flag": null,
"maps": [
{
"country": "",
"solution": "",
"solution_id": ""
}
],
"name_alpha_2": "SE",
"name_alpha_3": "SWE",
"numeric_code": "752"
},
] , // array of list
}
State List by Country id
Name: Get State List by Country id
Method : GET
Url : {{BASE_URL}}/api/v1/states-by-country/{{country_id}}?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
Response Example
JSON
{
"success" : True,
"message" : "State list",
"data" :[
{
"id": 1533,
"name": "Gävleborg County",
"country_code": "SE",
"iso2": "X"
},
] , // array of list
}
Cities List by State id
Name: Get Cities List by State id
Method : GET
Url : {{BASE_URL}}/api/v1/cities-by-state/{{state_id}}?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
Response Example
JSON
{
"success" : True,
"message" : "Cities list",
"data" :[
{
"id": 1533,
"name": "Gävleborg County",
"state_code": "X",
"country_code": "SE"
},
] , // array of list
}
Transaction
This section is about Paymid Transaction.
Transaction List (Simplified)
Name: Get Transaction List by Merchant Account ID
Method : GET
Url : {{base_url}}/api/v1/transaction/get-list?merchantAccountId={{your_account_no}}&page=1&status=Accepted&filterByRef=ref-5004
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
page : 1 // optional
You will get a paginated list of Transactions
Response Example
JSON
{
"success": true,
"message": "Transaction list",
"data": [
{
"type": "sale",
"status": "success",
"amount": "33.00",
"currency": "EUR",
"reference": "6jEoCGIVHC",
"created_at": "2024-12-18T12:24:20.000000Z",
"payment_method": "Card (VISA)",
"transaction_id": "1734524586GXHTTV8WJL"
},
...
...
{
"type": "sale",
"status": "success",
"amount": "55.00",
"currency": "USD",
"reference": "qR2mLtilQ2",
"created_at": "2024-12-23T07:15:53.000000Z",
"payment_method": "Card (VISA)",
"transaction_id": "17349380741KNQAWCAYU"
}
],
"pagination": {
"total": 106,
"current_items_count": 15,
"items_per_page": 15,
"current_page_no": 1,
"last_page_no": 8,
"has_more_pages": true
}
}
merchantAccountId : {{your_account_no}}
page : 1 // optional
status : Accepted // Accepted or Declined
filterByRef : ref-5004 // reference of the transaction
transactionType : sale // sale or payout
You can also filter the list by status, reference, type etc
Response Example
JSON
{
"success": true,
"message": "Transaction list",
"data": [
{
"type": "payout",
"status": "success",
"amount": "45.00",
"currency": "USD",
"reference": "ref-5004",
"created_at": "2025-06-05T08:53:08.000000Z",
"payment_method": "Card (VISA)",
"transaction_id": "56-9-4229389"
}
],
"pagination": {
"total": 1,
"current_items_count": 1,
"items_per_page": 15,
"current_page_no": 1,
"last_page_no": 1,
"has_more_pages": false
}
}
Transaction List (Extended)
Name: Get Transaction List by Merchant Account ID
Method : GET
Url : {{base_url}}/api/v1/transactions/list?merchantAccountId={{your_account_no}}&page=1&status=Declined&filterByRef=Re0hIIzQMq
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
page : 1 // optional
You will get a paginated list of Transactions
Response Example
JSON
{
"success": true,
"message": "Transaction list",
"data": [
{
"merchantId": 123,
"transactionId": "Re0hIIzQMq",
"txAmount": 50,
"txFee": 0,
"txTotalAmount": 50,
"txCurrency": "USD",
"baseAmount": 50,
"baseFeeAmount": 0,
"baseTotalAmount": 50,
"baseCurrency": "USD",
"status": "Declined",
"statusCode": "",
"errorMsg": "",
"customerBrowserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
"initialPsp": "Trust Payments",
"initialPspStatusCode": "",
"initialPspRefId": "A0234hmvx",
"initialPspMid": "",
"finalPsp": "Trust Payments",
"finalPspStatusCode": "",
"finalPspRefId": "",
"finalPspMid": "",
"paymentType": "Card",
"txType": "VISA",
"txMethod": "Deposit",
"cardScheme": "",
"cardBin": null,
"cardIssuer": "",
"cardIssuerCountry": "",
"maskedPan": "411111XXXXXX1111",
"cardHolderName": "",
"customerEmail": "[email protected]",
"customerFirstName": "John",
"customerLastName": "Doe",
"customerCountry": "AL",
"customerAddress": "SE",
"customerIpAddr": "103.187.94.96",
"customerIpCountry": "",
"customerIpRegion": "",
"customerIpCity": "",
"created": "2025-09-16 10:22:56",
"updated": "2025-09-16 10:22:58",
"updatedBy": "",
"kycStatus": false
},
...
...
{
"merchantId": 123,
"transactionId": "lrT9skagUT",
"txAmount": 50,
"txFee": 0,
"txTotalAmount": 50,
"txCurrency": "USD",
"baseAmount": 50,
"baseFeeAmount": 0,
"baseTotalAmount": 50,
"baseCurrency": "USD",
"status": "Declined",
"statusCode": "",
"errorMsg": "",
"customerBrowserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
"initialPsp": "Trust Payments",
"initialPspStatusCode": "",
"initialPspRefId": "A0234hmvx",
"initialPspMid": "",
"finalPsp": "Trust Payments",
"finalPspStatusCode": "",
"finalPspRefId": "",
"finalPspMid": "",
"paymentType": "Card",
"txType": "VISA",
"txMethod": "Deposit",
"cardScheme": "",
"cardBin": null,
"cardIssuer": "",
"cardIssuerCountry": "",
"maskedPan": "411111XXXXXX1111",
"cardHolderName": "",
"customerEmail": "[email protected]",
"customerFirstName": "John",
"customerLastName": "Doe",
"customerCountry": "AL",
"customerAddress": "SE",
"customerIpAddr": "103.187.94.96",
"customerIpCountry": "",
"customerIpRegion": "",
"customerIpCity": "",
"created": "2025-09-16 10:22:56",
"updated": "2025-09-16 10:22:58",
"updatedBy": "",
"kycStatus": false
},
],
"pagination": {
"currentPage": 10,
"lastPage": 148,
"perPage": 15,
"total": 2215,
"from": 136,
"to": 150
}
}
merchantAccountId : {{your_account_no}}
perPage : 20 // optional
page : 1 // optional
status : accepted // accepted / declined / pending
currency : USD // ISO 4217 format
filterByRef : lrT9skagUT // reference of the transaction
type : deposit // deposit or payout
startDate: 2025-09-01 06:10:30
endDate: 2025-09-16 06:10:30
updatedAtFrom : 2025-09-01 06:10:30
updatedAtTo : 2025-09-17 06:10:30
Response Example
JSON
{
"success": true,
"message": "Transaction list",
"data": [
{
"merchantId": 123,
"transactionId": "lrT9skagUT",
"txAmount": 50,
"txFee": 0,
"txTotalAmount": 50,
"txCurrency": "USD",
"baseAmount": 50,
"baseFeeAmount": 0,
"baseTotalAmount": 50,
"baseCurrency": "USD",
"status": "Declined",
"statusCode": "",
"errorMsg": "",
"customerBrowserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
"initialPsp": "Trust Payments",
"initialPspStatusCode": "",
"initialPspRefId": "A0234hmvx",
"initialPspMid": "",
"finalPsp": "Trust Payments",
"finalPspStatusCode": "",
"finalPspRefId": "",
"finalPspMid": "",
"paymentType": "Card",
"txType": "VISA",
"txMethod": "Deposit",
"cardScheme": "",
"cardBin": null,
"cardIssuer": "",
"cardIssuerCountry": "",
"maskedPan": "411111XXXXXX1111",
"cardHolderName": "",
"customerEmail": "[email protected]",
"customerFirstName": "John",
"customerLastName": "Doe",
"customerCountry": "AL",
"customerAddress": "SE",
"customerIpAddr": "103.187.94.96",
"customerIpCountry": "",
"customerIpRegion": "",
"customerIpCity": "",
"created": "2025-09-16 10:22:56",
"updated": "2025-09-16 10:22:58",
"updatedBy": "",
"kycStatus": false
},
],
"pagination": {
"currentPage": 1,
"lastPage": 1,
"perPage": 15,
"total": 1,
"from": 1,
"to": 1
}
}
Refund
Name: Payment Transaction Refund
Method : POST
Url : {{base_url}}/api/v1/payment-transaction/refund
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"reference":"w27Wd5JaIl",
"amount":"151",
"merchantAccountId":"100012"
}
Success Response Example
JSON
{
"success": true,
"message": "Refund request success.",
"data": {
"processor_reference": "5047869357",
"processor_reference_time": "2025-07-11 09:54:59",
"processor_status": "Refunded",
"status": "Refunded",
"amount": "120"
}
}
Failed Response Example
JSON
{
"success": false,
"message": "Refund not allowed for this solution.",
"errors": [
"Refund not allowed for this solution."
]
}
Get Request Status
Name: Get Payment/Payout Request Status
Method : GET
Url : {{BASE_URL}}/api/v1/payment/request-status
Description : Retrieve the current status of a payment or payout request using the reference ID. This is useful for checking transaction status without relying solely on webhooks.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Query Parameters
reference : {{transaction_reference}} // Required - The unique reference ID of the payment/payout request
merchantAccountId : {{your_account_no}} // Required
Response Example (Successful Payment)
JSON
{
"success": true,
"message": "Request status retrieved successfully",
"data": {
"reference": "payout_013503",
"merchantAccountId": "100002",
"status": "Accepted",
"transactionType": "payment",
"amount": "100.00",
"currency": "USD",
"customerEmail": "[email protected]",
"customerName": "John Doe",
"processorStatus": "Completed",
"processorReference": "TXN123456789",
"createdAt": "2025-12-25 10:30:45",
"updatedAt": "2025-12-25 10:31:12",
"paymentMethod": "Credit Card",
"solutionName": "Trust Payments"
}
}
Response Example (Pending Transaction)
JSON
{
"success": true,
"message": "Request status retrieved successfully",
"data": {
"reference": "payout_013504",
"merchantAccountId": "100002",
"status": "Pending",
"transactionType": "payout",
"amount": "250.00",
"currency": "EUR",
"customerEmail": "[email protected]",
"customerName": "Jane Smith",
"processorStatus": "Processing",
"processorReference": null,
"createdAt": "2025-12-26 14:20:30",
"updatedAt": "2025-12-26 14:20:30",
"paymentMethod": "Bank Transfer",
"solutionName": "SEPA Transfer"
}
}
Response Example (Failed Transaction)
JSON
{
"success": true,
"message": "Request status retrieved successfully",
"data": {
"reference": "payment_789012",
"merchantAccountId": "100002",
"status": "Failed",
"transactionType": "payment",
"amount": "75.50",
"currency": "GBP",
"customerEmail": "[email protected]",
"customerName": "Bob Johnson",
"processorStatus": "Declined",
"processorReference": "ERR_INSUFFICIENT_FUNDS",
"failureReason": "Insufficient funds in customer account",
"createdAt": "2025-12-27 09:15:20",
"updatedAt": "2025-12-27 09:15:45",
"paymentMethod": "Debit Card",
"solutionName": "Ecommpay"
}
}
Note: Possible status values include: Pending, Accepted, Failed, Refunded, Cancelled, Processing. Use this API to poll for transaction status updates or to verify webhook data.
API Configuration
This section reading about Paymid APi Configuration.
Basic Auth
Username & Password :
You can use "username" as "App key" and "password" will be "Secret Key" from the "Api Config" menu.
See the attached image
IPN & Webhook Setting
"IPN Url" This URL is used to receive hook data on new transaction complete or failure notifications.
You can set the IPN URL from Settings -> API Config.
If you wish to overwrite the Config you can also send webhookUrl url via the payment request payload (check payment request menu).
"Webhook Url" for getting transactions update Notification hook data.
Response Example
JSON
{
"type": "sale", //refund,payout
"amount": "24.00",
"status": "success", //success or failed
"reference": "O4j2V5thWT",
"transaction_id": "56-9-3485176",
"created_at": "2024-01-19T10:49:27.000000Z",
"payment_method": "Card (VISA)",
"processor_name": "Trust Payments",
"currency": "USD",
}
See the attached image
Verify Webhook with Signature
To ensure the integrity of webhook data, every webhook request includes a digital signature in the header. You should verify this signature using your Secrete Key before processing the request.
Signature Verification Steps
- Convert the payload into a JSON string (ensure proper formatting).
- In header, you will get the signature.
- Retrieve the JSON payload received from the webhook request.
- Alphabetically sort the payload before generating the signature.
- Generate an HMAC-SHA256 hash using the Settings -> Api Config -> Secrete Key as the apiSecret variable's value.
- Compare the generated signature with the signature received in the request headers.
// Payload received from webhook
$payload = [
"status" => "failed",
"type" => "sale",
"amount" => "55.00",
"reference" => "DazuknyVyG",
"transaction_id" => "A49dfkqvw",
"payment_method" => "Card (VISA)",
"created_at" => "2025-02-25 05:18:56",
"processor_name" => "Trust Payments",
"currency" => "USD"
];
// Fetch API Secret Text from settings/config
$apiSecret = getenv('API_SECRET') ?: 'default_secret'; // Replace with your actual config fetching logic
// Received signature (from the request headers or body)
$receivedSignature = "your_received_signature_here"; // Replace with the actual signature
// Step 1: Sort the payload by keys alphabetically
ksort($payload);
// Step 2: Convert payload to JSON string
$payloadJson = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
// Step 3: Generate HMAC signature using SHA-256
$generatedSignature = hash_hmac('sha256', $payloadJson, $apiSecret);
// Step 4: Verify the signature
if (hash_equals($generatedSignature, $receivedSignature)) {
echo "Signature is valid!";
} else {
echo "Signature is invalid!";
}
const crypto = require('crypto');
// Payload received from webhook
let payload = {
status: "failed",
type: "sale",
amount: "55.00",
reference: "DazuknyVyG",
transaction_id: "A49dfkqvw",
payment_method: "Card (VISA)",
created_at: "2025-02-25 05:18:56",
processor_name: "Trust Payments",
currency: "USD"
};
// Fetch API Secret Text from settings/config
const apiSecret = process.env.API_SECRET || 'default_secret'; // Replace with your actual config fetching logic
// Received signature (from the request headers or body)
const receivedSignature = "your_received_signature_here";
// Step 1: Sort the payload by keys alphabetically
payload = Object.keys(payload).sort().reduce((obj, key) => {
obj[key] = payload[key];
return obj;
}, {});
// Step 2: Convert payload to JSON string
const payloadJson = JSON.stringify(payload);
// Step 3: Generate HMAC signature using SHA-256
const generatedSignature = crypto.createHmac('sha256', apiSecret)
.update(payloadJson)
.digest('hex');
// Step 4: Verify the signature
if (generatedSignature === receivedSignature) {
console.log("Signature is valid!");
} else {
console.log("Signature is invalid!");
}
import hmac
import hashlib
import json
import os
# Payload received from webhook
payload = {
"status": "failed",
"type": "sale",
"amount": "55.00",
"reference": "DazuknyVyG",
"transaction_id": "A49dfkqvw",
"payment_method": "Card (VISA)",
"created_at": "2025-02-25 05:18:56",
"processor_name": "Trust Payments",
"currency": "USD"
}
# Fetch API Secret Text from settings/config
api_secret = os.getenv('API_SECRET', 'default_secret') # Replace with your actual config fetching logic
# Received signature (from the request headers or body)
received_signature = "your_received_signature_here"
# Step 1: Sort the payload by keys alphabetically
sorted_payload = dict(sorted(payload.items()))
# Step 2: Convert payload to JSON string
payload_json = json.dumps(sorted_payload, separators=(',', ':'))
# Step 3: Generate HMAC signature using SHA-256
generated_signature = hmac.new(
api_secret.encode('utf-8'),
payload_json.encode('utf-8'),
hashlib.sha256
).hexdigest()
# Step 4: Verify the signature
if hmac.compare_digest(generated_signature, received_signature):
print("Signature is valid!")
else:
print("Signature is invalid!")
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json;
class Program
{
static void Main()
{
// Payload received from webhook
var payload = new Dictionary
{
{ "status", "failed" },
{ "type", "sale" },
{ "amount", "55.00" },
{ "reference", "DazuknyVyG" },
{ "transaction_id", "A49dfkqvw" },
{ "payment_method", "Card (VISA)" },
{ "created_at", "2025-02-25 05:18:56" },
{ "processor_name", "Trust Payments" },
{ "currency", "USD" }
};
// Fetch API Secret Text from settings/config
string apiSecret = Environment.GetEnvironmentVariable("API_SECRET") ?? "default_secret"; // Replace with your actual config fetching logic
// Received signature (from the request headers or body)
string receivedSignature = "your_received_signature_here";
// Step 1: Sort the payload by keys alphabetically
var sortedPayload = payload.OrderBy(kvp => kvp.Key).ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
// Step 2: Convert payload to JSON string
string payloadJson = JsonConvert.SerializeObject(sortedPayload);
// Step 3: Generate HMAC signature using SHA-256
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))
{
byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(payloadJson));
string generatedSignature = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
// Step 4: Verify the signature
if (generatedSignature == receivedSignature)
{
Console.WriteLine("Signature is valid!");
}
else
{
Console.WriteLine("Signature is invalid!");
}
}
}
}
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.*;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import com.fasterxml.jackson.databind.ObjectMapper;
public class SignatureVerifier {
public static void main(String[] args) throws Exception {
// Payload received from webhook
Map payload = new HashMap<>();
payload.put("status", "failed");
payload.put("type", "sale");
payload.put("amount", "55.00");
payload.put("reference", "DazuknyVyG");
payload.put("transaction_id", "A49dfkqvw");
payload.put("payment_method", "Card (VISA)");
payload.put("created_at", "2025-02-25 05:18:56");
payload.put("processor_name", "Trust Payments");
payload.put("currency", "USD");
// Fetch API Secret Text from settings/config
String apiSecret = System.getenv("API_SECRET") != null ? System.getenv("API_SECRET") : "default_secret"; // Replace with your actual config fetching logic
// Received signature (from the request headers or body)
String receivedSignature = "your_received_signature_here";
// Step 1: Sort the payload by keys alphabetically
Map sortedPayload = new TreeMap<>(payload);
// Step 2: Convert payload to JSON string
ObjectMapper objectMapper = new ObjectMapper();
String payloadJson = objectMapper.writeValueAsString(sortedPayload);
// Step 3: Generate HMAC signature using SHA-256
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
sha256_HMAC.init(secret_key);
byte[] hashBytes = sha256_HMAC.doFinal(payloadJson.getBytes(StandardCharsets.UTF_8));
String generatedSignature = bytesToHex(hashBytes);
// Step 4: Verify the signature
if (generatedSignature.equals(receivedSignature)) {
System.out.println("Signature is valid!");
} else {
System.out.println("Signature is invalid!");
}
}
private static String bytesToHex(byte[] bytes) {
StringBuilder sb = new StringBuilder();
for (byte b : bytes) {
sb.append(String.format("%02x", b));
}
return sb.toString();
}
}
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"os"
"sort"
)
func main() {
// Payload received from webhook
payload := map[string]string{
"status": "failed",
"type": "sale",
"amount": "55.00",
"reference": "DazuknyVyG",
"transaction_id": "A49dfkqvw",
"payment_method": "Card (VISA)",
"created_at": "2025-02-25 05:18:56",
"processor_name": "Trust Payments",
"currency": "USD",
}
// Fetch API Secret Text from settings/config
apiSecret := os.Getenv("API_SECRET")
if apiSecret == "" {
apiSecret = "default_secret" // Replace with your actual config fetching logic
}
// Received signature (from the request headers or body)
receivedSignature := "your_received_signature_here" // Replace with the actual signature
// Step 1: Sort the payload by keys alphabetically
keys := make([]string, 0, len(payload))
for k := range payload {
keys = append(keys, k)
}
sort.Strings(keys)
sortedPayload := make(map[string]string, len(payload))
for _, k := range keys {
sortedPayload[k] = payload[k]
}
// Step 2: Convert payload to JSON string
payloadJSON, err := json.Marshal(sortedPayload)
if err != nil {
fmt.Println("Error marshalling payload:", err)
return
}
// Step 3: Generate HMAC signature using SHA-256
h := hmac.New(sha256.New, []byte(apiSecret))
h.Write(payloadJSON)
generatedSignature := hex.EncodeToString(h.Sum(nil))
// Step 4: Verify the signature
if hmac.Equal([]byte(generatedSignature), []byte(receivedSignature)) {
fmt.Println("Signature is valid!")
} else {
fmt.Println("Signature is invalid!")
}
}
import java.security.MessageDigest
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.util.*
import com.fasterxml.jackson.databind.ObjectMapper
fun main() {
// Payload received from webhook
val payload = mapOf(
"status" to "failed",
"type" to "sale",
"amount" to "55.00",
"reference" to "DazuknyVyG",
"transaction_id" to "A49dfkqvw",
"payment_method" to "Card (VISA)",
"created_at" to "2025-02-25 05:18:56",
"processor_name" to "Trust Payments",
"currency" to "USD"
)
// Fetch API Secret Text from settings/config
val apiSecret = System.getenv("API_SECRET") ?: "default_secret" // Replace with your actual config fetching logic
// Received signature (from the request headers or body)
val receivedSignature = "your_received_signature_here" // Replace with the actual signature
// Step 1: Sort the payload by keys alphabetically
val sortedPayload = payload.toSortedMap()
// Step 2: Convert payload to JSON string
val objectMapper = ObjectMapper()
val payloadJson = objectMapper.writeValueAsString(sortedPayload)
// Step 3: Generate HMAC signature using SHA-256
val generatedSignature = generateHmacSha256(payloadJson, apiSecret)
// Step 4: Verify the signature
if (generatedSignature == receivedSignature) {
println("Signature is valid!")
} else {
println("Signature is invalid!")
}
}
// Function to generate HMAC-SHA256 signature
fun generateHmacSha256(data: String, secret: String): String {
val mac = Mac.getInstance("HmacSHA256")
val secretKeySpec = SecretKeySpec(secret.toByteArray(Charsets.UTF_8), "HmacSHA256")
mac.init(secretKeySpec)
val hmacBytes = mac.doFinal(data.toByteArray(Charsets.UTF_8))
return bytesToHex(hmacBytes)
}
// Helper function to convert byte array to hex string
fun bytesToHex(bytes: ByteArray): String {
val hexString = StringBuilder()
for (b in bytes) {
hexString.append(String.format("%02x", b))
}
return hexString.toString()
}
Merchant Account Id
merchantAccountId :
And use the "Account No" as "merchantAccountId" from the "Api Config" menu.
See the attached image
Set your "IPN (Instant Payment Notification)" url for get transactions callback response.
Redirect URL's
Url's :
Here you can find "success url", "failed url" for redirect to actual urls after transaction.
As a merchant you send a reference & if you want that includes in the redirect you can add as {{reference_id}}.
So if you give reference like abcxyz123. And your customer will be redirected like example.com/return/success/abcxyz123.
See the attached images
Enable Solution
In order to enable various solutions you have to navigate over to "Select Solutions ->", once you try to enable them you will be prompted to input the required credentials that each solution provider requests.
Once you have entered the credentials you need to change "Status -> Active" and then click the "Save" button.
See the attached image
CLick to Enable button then filled all required field and Save.
Test Cards
Here is some dummy card details.
Success Cards :
4000000000000077
4111111111111111
4242424242424242
Decline Cards :
4917484589897107
CVV : 123
Date : 02/2029
Health Check
Name: Get Health Status for features
Method : GET
Url : {{BASE_URL}}/api/v1/health-report?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Response Example
JSON
{
"success": true,
"message": "Health Check Success",
"data": {
"payin": "healthy", // can be healthy, partially-healthy, unhealthy, maintenance
"payout": "healthy"
}
}
Get Public Key For Encryption
Name: Retrieve RSA Public Key for Payload Encryption
Method : GET
Url : {{BASE_URL}}/api/v1/payload-encryption-public-key?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Response Example
JSON
{
"success": true,
"message": "Public key retrieved successfully",
"data": {
"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvK7X+z5T6O... (truncated) ...\n-----END PUBLIC KEY-----",
"key_id": "key_20240101_001",
"algorithm": "RSA-OAEP-256"
}
}
Note: This public key is used to encrypt sensitive data (like card numbers and CVV) before sending it to the Hosted Fields or S2S APIs. Ensure you use the RSA-OAEP-256 padding scheme for encryption.
Customer Management
These APIs allow you to manage customer information and tokens for recurring payments. You can add customers, make payments using customer tokens, remove tokens, and regenerate tokens as needed.
Add Customer
Name: Add Customer
Method : POST
Url : {{BASE_URL}}/api/v1/add-customer
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName" : "John",
"middleName" : "",
"lastName" : "Doe",
"email" : "[email protected]",
"dob" : "1995-01-10",
"contactNumber" : "+1234567890",
"merchantAccountId" : "{{your_account_no}}",
"addressDetails" :
{
"country" : "Sweden",
"state" : "Stockholm",
"city" : "Dhaka",
"address" : "16/A, Stockholm",
"zipCode" : "11234"
}
}
Response
{
"success" : true,
"message" : "Success",
"data" :
{
"customer_reference_id" : "70e9efaf-2e72-4130-b38b-9552e2e94902",
"token" : "d04d2e57c700bc1d2c2da91d0e7b482a",
"expire_at" : "2025-11-05"
}
}
Payment Request Using Customer Token
Name: Payment Request Using Customer Token
Method : POST
Url : {{BASE_URL}}/api/v1/payment/request
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"customerToken" : "f0a8c83a1d4457b840b4376b9657b48e",
"reference" : "1XYOCJXEBFQ6",
"merchantAccountId" : "{{your_account_no}}",
"currency" : "USD",
"amount" : "25",
"ttl" : "10",
"tagName" : "XYOCJXEBF",
"webhookUrl" : "https://webhook.site/c31acfce-9887-4b29-b2f2-8aad83139c8c"
}
Response
{
"success" : true,
"message" : "Payment Request Accepted",
"data" :
{
"payment_url" : "https://sgw.paymid.com/secure-checkout/ab886b31-88bd-46fe-bec6-75f6b44f941b",
"reference" : "1XYOCJXEBFQ6"
}
}
See the attached image
Remove Customer Token
Name: Remove Customer Token
Method : POST
Url : {{BASE_URL}}/api/v1/remove-customer
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Form Data
{
"email" : "[email protected]",
"merchantAccountId" : "{{your_account_no}}"
}
Response
{
"success" : true,
"message" : "Success",
"data" :
[
"Success"
]
}
Customer Token Regenerate
Name: Customer Token Regenerate
Method : POST
Url : {{BASE_URL}}/api/v1/customer-refresh-token
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"email" : "[email protected]",
"merchantAccountId" : "{{your_account_no}}"
}
Response
{
"success" : true,
"message" : "Success",
"data" :
{
"customer_reference_id" : "70e9efaf-2e72-4130-b38b-9552e2e94902",
"token" : "f0a8c83a1d4457b840b4376b9657b48e",
"expire_at" : "2025-11-05"
}
}
Customer Histories
Name: Get Customer Histories by Merchant Account ID
Method : GET
Url : {{base_url}}/api/v1/customer/histories?merchantAccountId={{your_account_no}}&customerEmail=&perPage=20&page=1
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
customerEmail : ''
perPage : 20
page : 1
Response Example
JSON
{
"success": true,
"message": "Customer histories retrieved successfully",
"data": [
{
"reference_id": "B01E9POMTO",
"amount": 40,
"fee": 0,
"currency_code": "USD",
"transaction_status": "Accepted",
"customer_email": "[email protected]",
"customer_first_name": "Test",
"customer_last_name": "Test",
"customer_ip": null,
"kyc_status": false,
"created_at": "2025-12-03 08:26:14"
},
...
...
{
"reference_id": "CXVl45MUhl",
"amount": 25,
"fee": 0,
"currency_code": "USD",
"transaction_status": "Accepted",
"customer_email": "[email protected]",
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_ip": null,
"kyc_status": false,
"created_at": "2025-08-26 10:10:31"
}
],
"pagination": {
"current_page": 1,
"last_page": 4,
"per_page": 20,
"total": 71,
"from": 1,
"to": 20
},
"summary": {
"total_success_count": 48,
"total_success_volume": 3794,
"kyc_availability": {
"kyc_verified_count": 0,
"kyc_not_verified_count": 71,
"kyc_availability": false
}
}
}
Used Solutions by Customer
Name: Get Customer's Previously Used Solutions
Method : GET
Url : {{BASE_URL}}/api/v1/apm/customer-solutions
Description : Retrieve a list of payment solutions that have been previously used by a specific customer. This is useful for showing customers their preferred payment methods.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Query Parameters
merchantAaccountId : {{your_account_no}} // Required
customerToken : {{customer_token}} // Required
merchantSolutionStatus : Active // Optional (Active/Inactive)
type : Alternative Payments Methods // Optional (Alternative Payments Methods/Service Provider)
Response Example
JSON
{
"success": true,
"message": "Customer solutions retrieved successfully",
"data": [
{
"id": "2c032c79-dbb5-47b3-a575-c4098e687226",
"name": "Skrill",
"logo": "https://example.com/skrill-logo.png",
"type": "Alternative Payments Methods",
"status": "Active",
"supported_currencies": [
"USD",
"EUR",
"GBP"
],
"last_used": "2025-12-15 10:30:45"
},
{
"id": "485093e0-2ed6-466a-8573-7ee659db40c5",
"name": "Trust Payments",
"logo": "https://example.com/trust-logo.png",
"type": "Alternative Payments Methods",
"status": "Active",
"supported_currencies": [
"USD",
"EUR"
],
"last_used": "2025-12-10 14:22:11"
}
]
}
Note: This API returns only the solutions that the customer has previously used for transactions. You can filter by status and type to get specific solution categories.
Used Cards by Customer
Name: Get Customer's Previously Used Cards
Method : GET
Url : {{BASE_URL}}/api/v1/customer-card/previously-used-cards
Description : Retrieve a list of cards that have been previously used by a specific customer. This allows customers to quickly select from their saved payment methods.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Query Parameters
merchantAaccountId : {{your_account_no}} // Required
customerToken : {{customer_token}} // Required
Response Example
JSON
{
"success": true,
"message": "Previously used cards retrieved successfully",
"data": [
{
"cardToken": "6d044049-5c2f-4b25-8eb3-6e1ad20e4578",
"cardBrand": "Visa",
"lastFourDigits": "4242",
"expiryMonth": "12",
"expiryYear": "2026",
"cardHolderName": "John Doe",
"isDefault": true,
"lastUsed": "2025-12-20 15:30:22",
"createdAt": "2025-11-15 10:20:15"
},
{
"cardToken": "8a2f3c1d-9e4b-4f2a-a1c3-7d8e9f0a1b2c",
"cardBrand": "Mastercard",
"lastFourDigits": "5555",
"expiryMonth": "06",
"expiryYear": "2027",
"cardHolderName": "John Doe",
"isDefault": false,
"lastUsed": "2025-12-18 09:45:33",
"createdAt": "2025-10-22 14:12:08"
}
]
}
Note: The card tokens returned can be used with the "Payment Request with Token" API to process payments without requiring the customer to re-enter card details.
Hosted Payout Page
This section explains about Hosted Payout Process.
Payout Request
Name: Make Payout Request
Method : POST
Url : {{base_url}}/api/v1/payout/request
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"merchantAccountId" :"{{your_account_no}}",
"reference":"ref-0001", // unique and must be at least 10 characters and special characters are not allowed
"country":"Sweden",
"dob":"1994-12-21",
"firstName":"John",
"lastName":"Doe",
"email":"[email protected]",
"contactNumber":"+01234567890",
"postcode":"12345",
"premise":"1234",
"street":"Unnamed Road",
"state":"Blekinge",
"town":"Kallinge",
"amount":"45",
"currency":"USD",
"payoutType":"", // optional, can be either cardPayout or bankPayout
"solutionId":"f0850594-efc0-449b-b0ab-7ada65dcd56a", // optional
"webhookUrl":"{{webhookUrl}}" // optional
}
Response Example
JSON
{
"success": true,
"message": "Payout request created successfully",
"data": {
"payout_url": "https://sgw.paymid.com/secure-payout/c32b46f8-d9b1-482f-b596-4c3a4f227426",
"reference": "ref-5001"
}
}
Payout with Token
Name: Make Payout Request with Customer Token which can be generated using customer info.
Method : POST
Url : {{base_url}}/api/v1/payout/request
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"merchantAccountId" :"{{your_account_no}}",
"customerToken":"9b18c3f97440add095b7d67527e306e5",
"reference":"ref-5015", // unique and must be at least 10 characters and special characters are not allowed
"currency":"USD",
"amount":"27",
"payoutType":"", // optional, can be either cardPayout or bankPayout
"solutionId":"f0850594-efc0-449b-b0ab-7ada65dcd56a", // optional
"webhookUrl":"{{webhookUrl}}" // optional
}
Response Example
JSON
{
"success": true,
"message": "Payout request created successfully",
"data": {
"payout_url": "https://sgw.paymid.com/secure-payout/24fbae5b-3ad0-4702-bd4a-c31f5a0db233",
"reference": "ref-5015"
}
}
Get Payout Approval List
Name: Get Payout Approval List
Method : GET
Url : {{BASE_URL}}/api/v1/payment/payout-approval/list
Description : Retrieve a list of payout requests that are pending approval. This is useful for merchants who have approval workflows enabled for payouts.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Query Parameters
merchantAccountId : {{your_account_no}} // Required
filterByEmail : [email protected] // Optional - Filter by customer email
page : 1 // Optional - Page number for pagination
perPage : 20 // Optional - Number of items per page
Response Example
JSON
{
"success": true,
"message": "Payout approval list retrieved successfully",
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reference": "payout_013503",
"merchantAccountId": "100002",
"customerEmail": "[email protected]",
"customerName": "Pete Smith",
"amount": "500.00",
"currency": "USD",
"payoutType": "bankPayout",
"status": "Pending Approval",
"requestedBy": "[email protected]",
"requestedAt": "2025-12-28 10:30:45",
"approvalRequired": true,
"approvers": [
{
"email": "[email protected]",
"status": "Pending"
},
{
"email": "[email protected]",
"status": "Approved"
}
],
"bankDetails": {
"accountName": "Pete Smith",
"accountNumber": "****5678",
"bankName": "Example Bank"
}
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"reference": "payout_013504",
"merchantAccountId": "100002",
"customerEmail": "[email protected]",
"customerName": "Jane Smith",
"amount": "250.00",
"currency": "EUR",
"payoutType": "cardPayout",
"status": "Pending Approval",
"requestedBy": "[email protected]",
"requestedAt": "2025-12-28 14:15:20",
"approvalRequired": true,
"approvers": [
{
"email": "[email protected]",
"status": "Pending"
}
],
"cardDetails": {
"cardBrand": "Visa",
"lastFourDigits": "4242"
}
}
],
"pagination": {
"current_page": 1,
"last_page": 3,
"per_page": 20,
"total": 45,
"from": 1,
"to": 20
}
}
Note: This API returns only payout requests that require approval. Use the filterByEmail parameter to narrow down results to a specific customer. The approval status can be: Pending, Approved, Rejected.
Payout
This section explains about Payout.
Bank Payout
Name: Make Bank Payouts
Method : POST
Url : {{base_url}}/api/v1/payout/process
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"basicProfile": {
"country": "Sweden",
"dob": "2024-04-01", // format must be yyyy-mm-dd
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"contactNumber": "9034893274",
"postcode": "11115",
"premise": "Stockholmes",
"street": "Stockholmes",
"state": "Dalarna County",
"town": "Borlänge"
},
"processorRequiredFields": {
"accountName": "John Doe",
"accountNumber": "5648915103",
"bankName": "SIAM COMMERCIAL BANK PUBLIC COMPANY LTD.",
"bankCode": "014"
},
"reference": "papaya-123q", // unique and must be at least 10 characters and special characters are not allowed
"merchantAccountId": "{{your_account_no}}",
"amount": "10",
"currency": "THB", // ISO 4217 format
"solutionId": "{{solutionId}}", // Id from Solution list
"payoutType": "bankPayout"
}
Response Example
JSON
{
"success": true,
"message": "Bank Payout Processed",
"data": {
"success": true,
"reference_id": "55-DuqXNBv0Q7",
"redirect_to": null
}
}
Bank Payout Processor Required Fields
Name: Get Bank Payout Details
Method : GET
Url : {{base_url}}/api/v1/get-bank-payout-details/{{solutionId}}?merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Response Example
JSON
{
"success": true,
"message": "success",
"data": [
{
"name": "Account Name",
"type": "text",
"value": null,
"required": "true",
"input_name": "accountName"
},
{
"name": "Account Number",
"type": "text",
"value": null,
"required": "true",
"input_name": "accountNumber"
},
{
"name": "Bank Name",
"type": "text",
"value": null,
"required": "true",
"input_name": "bankName"
},
{
"name": "Bank Code",
"type": "text",
"value": null,
"required": "true",
"input_name": "bankCode"
}
]
}
Card Payout
Name: Make Card Payouts
Method : POST
Url : {{base_url}}/api/v1/payout/process
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"basicProfile": {
"country": "Sweden",
"dob": "2006-07-09", // format must be yyyy-mm-dd
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"contactNumber": "9034893274",
"postcode": "11115",
"premise": "Stockholmes",
"street": "Stockholmes",
"state": "Gävleborg County",
"town": "Alfta"
},
"processorRequiredFields": {
"expiryDate": "02/2025",
"card": "4111111111111111",
"cardName": "John Doe",
"secret": "123"
},
"reference": "IC-Payout-0011", // unique and must be at least 10 characters and special characters are not allowed
"merchantAccountId": "{{your_account_no}}",
"amount": "50.00",
"currency": "USD", // ISO 4217 format
"solutionId": "{{solutionId}}", // Id from Solution list
"payoutType": "cardPayout"
}
Response Example
JSON
{
"success": true,
"message": "Card Payout Processed",
"data": {
"success": true,
"reference_id": "11-DuqXNBv0Q2",
"redirect_to": null
}
}
Get Solution List
Name: Get Solution List by Merchant Account ID
Method : GET
Url : {{base_url}}/api/v1/merchant/active/solutions?payout_type=bankPayout&merchantAccountId={{your_account_no}}
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
payout_type : bankPayout // or cardPayout
Response Example
JSON
{
"success": true,
"message": "Success",
"data": [
{
"id": "269b8d4a-151e-4f17-b3f0-050277618ac2", // this Solution ID is required in other requests
"name": "Trust Payments",
"logo": "https://centralisera-staging.s3.amazonaws.com/solution/logo/63d134c84edb5490.jpg",
"supported_currencies": [
"USD",
"EURO"
],
"regions": [
"Africa"
],
"dynamic_currency_supported": 1
}
]
}
Server to Server
This section explains about Server to Server Payments.
Direct Server to Server Payment
Name: Make Direct Server to Server Payments
Method : POST
Url : {{base_url}}/api/v1/payment/process-transaction
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "John",
"middleName": "", // optional
"lastName": "Doe",
"reference": "DuqXNBv0Q", // must be more than 10 characters and special characters are not allowed
"email": "[email protected]",
"dob": "1990-01-01", // format must be yyyy-mm-dd
"contactNumber": "+12345678",
"address": "SE",
"country": "Sweden",
"state": "N/A",
"city": "N/A",
"zipCode": "1212",
"currency": "USD", // ISO 4217 format
"amount": "55.00",
"ttl": 5,
"tagName": "VIP Tag",
"webhookUrl": "", // optional
"merchantAccountId": "{{your_account_no}}",
"solutionUniqueId": [],
"card": "{{test_card}}",
"secret": "123",
"expiry_date": "06/24",
"card_name": "MD X",
"customerBrowserUserAgent": "Mozilla 52.0",
"customerIP": "1.1.1.1"
}
2D Success Response Example
JSON
{
"success": true,
"message": "Payment Request Processed",
"data": {
"success": true,
"reference_id": "11-DuqXNBv0Q2",
"redirect_to": null
}
}
3D Redirect URL Response Example
JSON
{
"success": true,
"message": "Payment Request Failed",
"data": {
"success": true,
"reference_id": "11-DuqXNBv0Q",
"redirect_to": "https://staging.centralisera.com/three_d/acs/redirect?payment_id=11-DuqXNBv0Q"
}
}
Auth Error Response Example
JSON
{
"success": false,
"message": "Merchant Authentication failed",
"errors": {
"Auth": [
"Merchant Authentication failed"
]
}
}
S2S APM Required Fields
Name: Get Direct Server to Server APM Payments Required Fields
Method : GET
Url : {{base_url}}/api/v1/get-apm-s2s-requirement/{{solutionUuid}}?merchantAccountId={{your_account_no}}&type=payin
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
type : payin // or payout
Response Example
JSON
response :
{
"success": true,
"message": "success.",
"data": [
{
"name": "Ewallet Account",
"type": "text",
"value": null,
"required": "true",
"input_name": "ewallet_account_id"
}
]
}
S2S APM Payment Process
Method : POST
Url : {{base_url}}/api/v1/payment/process-apm-transaction
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "Danny",
"middleName": "",
"lastName": "Jack",
"reference": "XYOCJXEBFJACK0001",
"email": "[email protected]",
"dob": "1994-12-20",
"contactNumber": "01234567890",
"merchantAccountId": "{{your_account_no}}",
"address": "Mombasa, Kenya",
"country": "Kenya",
"state": "Mombasa",
"city": "Mombasa",
"zipCode": "11115",
"currency": "KES",
"amount": "30",
"ttl": "10",
"tagName": "",
"solutionUniqueId": ["f5a112d7-77f6-4573-8b54-1a3d9d59f750"],
"isRecurring":"",
"recurringInterval":"",
"customerBrowserUserAgent":"mozila firefox",
"customerIP":"172.0.0.1",
"additionalInfo":{
"ewallet_account_id":"+254111111111", // MPESA example
"document":"11111111111" // PIX/Monetix example (CPF/CNPJ)
} // get required fields from "S2S APM Required Fields" api
}
Response Example
JSON
{
"success": true,
"message": "Payment initiated",
"data": {
"payment_url": "https://sandbox.cardpay.com/MI/payments/redirect?token=AB5106c2HDBe0c44f3cF7DF5",
"reference": "XYOCJXEBFJACK0002"
}
}
S2S APM Payment with Customer Token
Method : POST
Url : {{base_url}}/api/v1/payment/process-apm-transaction
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"customerToken":"4fd158b995xxxxxxxxxed981020f",
"reference": "XYOCJXEBFJACK0002",
"merchantAccountId": "{{your_account_no}}",
"currency": "KES",
"amount": "20",
"ttl": "10",
"tagName": "",
"solutionUniqueId": ["f5a112d7-77f6-4573-8b54-1a3d9d59f750"],
"isRecurring":"",
"recurringInterval":"",
"customerBrowserUserAgent":"mozila firefox",
"customerIP":"172.0.0.1",
"additionalInfo":{
"ewallet_account_id":"+254111111111", // MPESA example
"document":"11111111111" // PIX/Monetix example (CPF/CNPJ)
} // get from api
}
Response Example
JSON
{
"success": true,
"message": "Payment initiated",
"data": {
"payment_url": "https://sandbox.cardpay.com/MI/payments/redirect?token=AB5106c2HDBe0c44f3cF7DF5",
"reference": "XYOCJXEBFJACK0002"
}
}
Response Example
JSON
{
"success": true,
"message": "Payment initiated",
"data": {
"payment_url": "https://sandbox.cardpay.com/MI/payments/redirect?token=AB5106c2HDBe0c44f3cF7DF5",
"reference": "XYOCJXEBFJACK0002"
}
}
Hosted Fields
This section explains Hosted Fields payment processing. Hosted Fields allows you to securely collect and process payment information with encrypted card data, providing PCI-compliant payment processing.
HF Process with Card Token
Name: Hosted Fields Process Transaction with Card Token
Method : POST
Url : {{BASE_URL}}/api/v1/payment/hf-process-transaction
Description : Process a payment using a previously saved card token with encrypted secret. This method is ideal for returning customers who have saved their card information.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"merchantAccountId": "{{yourMerchantAccountId}}",
"customerToken": "73024c3fd651fea6a5ee404fe49bd0dc",
"cardToken": "6d044049-5c2f-4b25-8eb3-6e1ad20e4578",
"secret": "TzVaa5uSeHNggUJk7Rju6IPM7D1eS7CXwS0TFBgio65bB35wjzw7tHucC7KcWS5s87v6aBRZmt5EBLAD3xk++nBk7Ki0ieWHiytqP+9adTvwzMC+awM5SiLw9e/BQn7cpiFlrlN7eECiDAOIarX4NOOhIshNtVhUfBQuCshIz78vcMft7QsXAAV2OLUaaUqrzwWqJqjYhpUMf4W0XbD9x0tjX/qDpbpOgwilfTyMuhxsd2uSQyPxQBWI+FSPcoBqvk2qowhvXXg6PHfJlCQ7RcX19fLyItk64rdlLwL4+h4DiffJdiYd02HI/YXWdX480Ef70y3sWLas6IPs58Z+Ug==",
"customerBrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
"customerIP": "92.251.41.84",
"reference": "62617-5378", // Optional - unique reference ID
"currency": "EUR",
"depositCurrency": null, // Optional - for currency conversion
"amount": 56,
"ttl": 15, // Optional - time to live in minutes
"tagName": null, // Optional
"solutionUniqueId": ["2c032c79-dbb5-47b3-a575-c4098e687226"],
"serverToServer": true,
"successUrl": "https://google.com/success",
"failedUrl": "https://google.com/failed",
"is_hosted_fields_encrypted": true // Required - must be true for encrypted data
}
Response Example
JSON
{
"success": true,
"message": "Payment processed successfully",
"data": {
"reference": "62617-5378",
"status": "Accepted",
"transactionId": "txn_abc123xyz",
"amount": "56.00",
"currency": "EUR",
"processorReference": "PROC_REF_123456",
"createdAt": "2025-12-28 10:30:45"
}
}
Note: The cardToken can be obtained from the "Used Cards by Customer" API. The secret must be encrypted using the Hosted Fields encryption library. Set is_hosted_fields_encrypted to true when using encrypted data.
HF Process APM with Payment Token
Name: Hosted Fields Process APM Transaction with Payment Token
Method : POST
Url : {{BASE_URL}}/api/v1/payment/process-apm-transaction
Description : Process an Alternative Payment Method (APM) transaction using a payment token. This is used for APM solutions like Skrill, PayPal, or other digital wallets.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"amount": "25",
"currency": "EUR",
"reference": "JYDFOOWSBJL",
"customerIP": "81.38.67.137",
"successUrl": "https://example.com/transaction-result/redirect",
"webhookUrl": "https://example.com/transaction-result/webhook?operatorId=301&paymentGatewayId=HDPlNDeqRQSZfFg5aTm7nA&locale=en",
"paymentToken": "9b33a6a1-6a9d-4e43-bee6-9b86ceab208d",
"customerToken": "2e7dcfb6fb2d84d1c7740bc5fef2e3aa",
"solutionUniqueId": [
"2c032c79-dbb5-47b3-a575-c4098e687226"
],
"merchantAccountId": "100643",
"merchantAaccountId": "100643", // Alternative parameter name (typo in original API)
"customerBrowserUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"
}
Response Example
JSON
{
"success": true,
"message": "APM payment initiated",
"data": {
"reference": "JYDFOOWSBJL",
"status": "Pending",
"redirectUrl": "https://apm-provider.com/checkout?token=xyz123",
"paymentToken": "9b33a6a1-6a9d-4e43-bee6-9b86ceab208d",
"transactionId": "txn_apm_456789",
"amount": "25.00",
"currency": "EUR",
"createdAt": "2025-12-28 11:15:30"
}
}
Note: The paymentToken is generated during the initial APM setup. The customer will be redirected to the APM provider's page to complete the payment. Webhook notifications will be sent to the specified webhookUrl upon transaction completion.
HF Process with Encrypted Data
Name: Hosted Fields Process with Encrypted Card Data and Customer Token
Method : POST
Url : {{BASE_URL}}/api/v1/payment/hf-process-transaction
Description : Process a payment using fully encrypted card data including card number, cardholder name, expiry date, and CVV. This provides the highest level of PCI compliance as sensitive card data never touches your servers in plain text.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"customerToken": "2e7dcfb6fb2d84d1c7740bc5fef2e3aa",
"currency": "EUR",
"amount": "1000",
"webhookUrl": "https://example.com/transaction-result/webhook?operatorId=100643&locale=en",
"solutionUniqueId": ["6a9b09ea-3313-4577-a6de-f9be9d04caf1"],
"merchantAccountId": "100643",
"card_name": "gcBqQaEykuq/kIBl5dfa+MzuT0rx5eN6PiB+Tr+6LwqI8NlWiRxGbTCyivJbLf1+MYfUpKjy7CIOBwEuDvpJbJV0FLhVxbbV07U6bf0oK+QqoXNWfMwyAoXwETcdG4tGUdDgL+Swbs9lbvkRonEx3ucNE33pB7oPGivZvzFz26uCmomC+/pagTP379Yp5MebjIKwlUygi90lX9BIafbWIjeQ09a4qENmrGEwPmJpby7FcB7mIeSoKIeRW8VtJQPUOyq4YeaxFEWgDK0BPYp+CpxSKHpQ68a2DP5bIWGE6aEF1QUgj1msOPuxM9W1ZcEXCq9VjzP/rIN6AO4HdhSptA==",
"card": "MhQnymw22QorvinVObtaFsQgWuOwYKMY9eJgg+l3UD1KNCRaD1KFuXVQQ7ySuHrQFSiVpCZLlrBEHrLeJJiyRn/O2fOH9QI3UhavAnxFZHzdKNHfpa+XD7zmYwlEiHGvnGELUPaVS5coLM61R6cbeMA9dj2gS8MZFwJcKqOMohhw8BQOLmqrJayfkfARaiEAl6r8c1+X7B4+n8oAgK4ZbEU1asEChd4iDhY5E87LXzlHLMHLu8SQGhJj9z2JUnZrRKOOkh+j0qSfhAKOoF8P1qOf8Vtf8KLL9fgv7rMQJ7NqJqtmFeR2bltjPb2NR7qpmdG5sFGdnhbhOgr56GKC4Q==",
"secret": "hJttJGsNkYQOP+VnIonwIRhPJI7icZcrRCUoqqhBveeSZ/FOEn1Wxlgaaz17Jsme5SNunPeDlac+IpYLYeUClDKCDlU1BpVE6KFNUJBCHY6PNwo9sjVpfcCoCtqrst5D53AMxK7LCop0STpMuQEBza59DVKdiyYPt4t+RNBmjONQrlN3PvnVcXKarApRlwXtOnbjfm2qDgOEjJCmFjJYUGhIfELs1xb+0yup/6+OCP4mpsV0udXc4kQEqpbUuqQ5zYQkM+69/Kzw3nR7o63yNsHVpk30hS41u3pNtUZkglPECdrSuWqBazZHZJuYP+zjfozpDb63YZPZv8q7T1fyKQ==",
"expiry_date": "QKDjud9HT3tA8EmrZNuYz5CXyqXWF6xC4OrhS/csSMTmAQvzg7HXPd2RBsqA1wHRut8NUtpk2V+6tPoj53G8dap73QpSifkqy9jQj6msxQW+Xv5uua0SOOiJYHc/QDLlmBXCL5wasRgihrAnQQp2Mud04/1tMWx2r4V6sVXEaswiCGHNyHtpzs15JDFE7X26gczUG+B64QjwSUPxKhbYSxA/QEoZB/NILebQAF8BhFMfV48SvbV7AW5B2VTgH3HVVTlTjXB9csVRYRgVWy7qCSw9+fZvrZhDbjtIt3OjX70u4rvkK/TaGuDQsx7vohE6zPZOr+I38ekaRCTxAwC4vw==",
"customerBrowserUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.93 Safari/537.36",
"customerIP": "103.213.242.81",
"is_hosted_fields_encrypted": true // Required - must be true
}
Important: All card data fields (card_name, card, expiry_date, secret) must be encrypted using the Paymid Hosted Fields encryption library before sending to the API.
Response Example
JSON
{
"success": true,
"message": "Payment processed successfully",
"data": {
"reference": "auto_generated_ref_123",
"status": "Accepted",
"transactionId": "txn_encrypted_789xyz",
"amount": "1000.00",
"currency": "EUR",
"processorReference": "PROC_ENC_456789",
"cardBrand": "Visa",
"lastFourDigits": "4242",
"createdAt": "2025-12-28 12:45:20"
}
}
Note: This method provides maximum security as card data is encrypted on the client side before transmission. The encryption library can be obtained from your Paymid account dashboard. All encrypted fields are Base64-encoded encrypted strings.
Paymid Recurring
This section explains about Recurring Payment Requests.
Recurring Payment
Name: Payment Request with Recurring Enable
Method : POST
Url : {{base_url}}/api/v1/payment/request
Description : If there is a trial/initial period before the recurring payment starts, then trialAmount and trialInterval should be added. For example: if trialAmount is 10 and trialInterval is 3 then first payment will be 10 and after 3 days, the actual recurring payment of 50 will occur each 30 days.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "John",
"middleName": "", // optional
"lastName": "Doe",
"reference": "DuqXNBv0QQ-13",
"email": "[email protected]",
"dob": "1990-01-01", // format must be yyyy-mm-dd
"contactNumber": "+12345678",
"address": "SE",
"country": "Sweden",
"state": "N/A",
"city": "N/A",
"zipCode": "1212",
"currency": "USD", // ISO 4217 format
"amount": "55.00",
"ttl": 5,
"tagName": "VIP Tag",
"webhookUrl": "", // optional
"merchantAccountId": "{{your_account_no}}",
"solutionUniqueId": [],
"isRecurring": 1,
"recurringInterval": 30,
"recurringAmount": 50,
"trialAmount": 10, // optional
"trialInterval": 3, // optional
}
Response Example
JSON
{
"success": true,
"message": "Payment Request Accepted",
"data": {
"payment_url": "https://sgw.paymid.com/checkout-page/38e65db8-5934-48a8-a569-4038c50d1b23"
}
}
Subscription List
Name: Get Subscription List by Merchant Account ID
Method : GET
Url : {{base_url}}/api/v1/subscriptions/get-list?merchantAccountId={{your_account_no}}&page=1&status=active
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Param
merchantAccountId : {{your_account_no}}
page : 1 // optional
status : active // active or inactive or cancelled
Response Example
JSON
{
"success": true,
"message": "success.",
"data": [
{
"subscription_id": "209de9e7-c4d0-400e-b463-928ca1d6343a",
"amount": "55",
"status": "active",
"last_payment_status": "success",
"start_date": "2024-04-25 10:23:37"
},
{
"subscription_id": "491e66ee-a8bb-4b2b-bcb3-eb95fe787924",
"amount": "55",
"status": "active",
"last_payment_status": "success",
"start_date": "2024-05-02 15:18:34"
},
{
"subscription_id": "8af65bbc-b160-4e32-8909-f5b21d0d8852",
"amount": "55",
"status": "active",
"last_payment_status": "success",
"start_date": "2024-05-13 19:06:14"
},
{
"subscription_id": "03cdef06-1ae1-44c0-b674-eabdf30f6c20",
"amount": "55",
"status": "active",
"last_payment_status": "success",
"start_date": "2024-06-21 19:42:28"
}
],
"pagination": {
"total": 4,
"current_items_count": 4,
"items_per_page": 10,
"current_page_no": 1,
"last_page_no": 1,
"has_more_pages": false
}
}
Update Subscription (Card)
Name: Update Card of the existing subscription
Method : POST
Url : {{base_url}}/api/v1/payment/request
Description : If you need to update card of any existing subscription. Just make 0 amount payment request with the existing subscription_id as additionalInfo in payload. As soon as the payment is approved, the card will be updated on the existing subscription uuid.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "John",
"middleName": "", // optional
"lastName": "Doe",
"reference": "DuqXNBv0QQ-13",
"email": "[email protected]",
"dob": "1990-01-01", // format must be yyyy-mm-dd
"contactNumber": "+12345678",
"address": "SE",
"country": "Sweden",
"state": "N/A",
"city": "N/A",
"zipCode": "1212",
"currency": "USD", // ISO 4217 format
"amount": "0.00", // amount must be 0 in this case
"ttl": 5,
"tagName": "VIP Tag",
"merchantAccountId": "{{your_account_no}}",
"solutionUniqueId": [],
"isRecurring": 1,
"additionalInfo": {
"subscription_id": "209de9e7-c4d0-400e-b463-928ca1d6343a"
},
}
Response Example
JSON
{
"success": True,
"message": "Payment request accepted",
"data": {
"payment_url": "https://sgw.paymid.com/secure-payment/2bfec39f-55dc-4f48-976b-9d37b1675007"
}
}
Cancel Subscription
Name: Cancel Subscription by Merchant Account ID
Method : POST
Url : {{base_url}}/api/v1/subscriptions/cancel
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"merchantAccountId": "{{your_account_no}}",
"subscription_id": "03cdef06-1ae1-44c0-b674-eabdf30f6c20" // Actual subscription_id from your list
}
Response Example
JSON
{
"success": true,
"message": "success.",
"data": {
"subscription_id": "03cdef06-1ae1-44c0-b674-eabdf30f6c20",
"status": "cancelled"
}
}
Withdrawal
This section explains about Withdrawal Flow. Below are the 5 steps for withdrawal.
- Add Customer (Create Customer Token)
- Create Payment Request (With Token)
- Complete Payment (via Secure Checkout)
- Get Card Token
- Withdrawal Request
1. Add Customer
Name: Add Customer (Create Customer Token)
Method : POST
Url : {{base_url}}/api/v1/add-customer
Description : Before processing withdrawals with a card token, you must first create a customer token. The token will only be visible once during creation — store it securely. If lost, you can regenerate it using the customer’s email.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"firstName": "Don",
"middleName": "",
"lastName": "Danny",
"email": "[email protected]",
"dob": "1995-01-10",
"contactNumber": "+1234567890",
"merchantAccountId": "{{your_account_no}}",
"addressDetails": {
"country": "Sweden",
"state": "Stockholm",
"city": "Dhaka",
"address": "16/A, Stockholm",
"zipCode": "11234"
}
}
Response Example
JSON
{
"success": true,
"message": "Success",
"data": {
"customer_reference_id": "b86c68e5-9a14-4e49-b55e-e7f2285110a9",
"token": "56f74d8274c1cb387e1ad24895905c18",
"expire_at": "2026-03-02"
}
}
2. Create Payment Request
Name: Create Payment Request (With Token)
Method : POST
Url : {{base_url}}/api/v1/payment/request
Description : Use the customer token from step 1 to initiate a payment. This returns a secure payment URL for the user to complete the payment.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"customerToken": "56f74d8274c1cb387e1ad24895905c18",
"reference": "1XYOCJXEBFQ9",
"merchantAccountId": "{{your_account_no}}",
"currency": "USD",
"amount": "50",
"webhookUrl": "https://webhook.site/b4d48b6d-f965-4bf8-b1bd-180248c6922e"
}
Response Example
JSON
{
"success": true,
"message": "Payment Request Accepted",
"data": {
"payment_url": "https://sgw.paymid.com/secure-checkout/ef65e8ff-4768-4fc5-bd34-c549d9414222",
"reference": "1XYOCJXEBFQ9",
"session_id": "ef65e8ff-4768-4fc5-bd34-c549d9414222"
}
}
3. Complete Payment
Name: Complete Payment (via Secure Checkout)
Method : POST
Url : {{base_url}}/api/v1/payment/request
Description :
- - Open the payment_url in a browser.
- - Enter valid card details.
- - On success, a card token will be created and linked to the customer.
- for details check here Payment With Token
4. Get Card Token
Name: Get Card Token
Method : GET
Url : {{base_url}}/api/v1/get-withdrawal-customer/card?merchantAccountId={{your_account_no}}&customerReferenceId={{customer_reference_id}}&email={{customer_email_address}}
Description :
Retrieve the stored card token(s) linked to a customer
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Response Example
JSON
{
"success": true,
"message": "success",
"data": [
{
"card_token": "b1fbc631-8089-4000-806c-4984adacb3b3",
"card_number": "411111XXXXXX1111",
"expiry_date": "*******",
"card_type": "VISA",
"card_name": "JO****OE",
"customer": {
"customer_reference_id": "8160a328-4906-4835-9071-599702e96f33",
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"email": "[email protected]"
},
"solution": {
"alias_name": "Trust Payments"
}
}
]
}
5. Withdrawal Request
Name: Withdrawal Request
Method : POST
Url : {{base_url}}/api/v1/payment/withdrawal
Description :
Withdraw funds using the card token and customer reference ID. The withdrawal process works as follows:
- First, it tries to process a refund from previous deposits.
- If the refund is successful, the refund amount is applied.
- Any remaining balance will be sent as a payout transaction.
Withdraw funds using the card token and customer reference ID. The withdrawal process works as follows:
- First, it tries to process a refund from previous deposits.
- If the refund is successful, the refund amount is applied.
- Any remaining balance will be sent as a payout transaction.
Authorization
Basic Auth
Username : App Key
Password : Secret Key
Body
Raw JSON
{
"customerToken": "",
"customerReferenceId": "b86c68e5-9a14-4e49-b55e-e7f2285110a9",
"cardToken": "0ec8e87d-5f0c-4748-ba7c-41992d717c2d",
"reference": "BYOCJXEBFR18",
"merchantAaccountId": "{{yourMerchantAccountId}}",
"currency": "USD",
"amount": "125"
}
Response Example
JSON
{
"success": true,
"message": "success",
"data": []
}