Our Payment Methods API allows you to retrieve a list of available payment methods supported by Pay1st. This API uses GET to retrieve the payment method information and returns a JSON response containing details about each payment method. Integrating this will enable you to show Pay1st payment methods on your native platform.
Request And Headers
Request
To retrieve a list of available payment methods, make a GET request to the following endpoint:
GET /api/shop/payments/channels/hosted/external-groupings?platform=<PLATFORM>&countryCode=\<COUNTRY_CODE>&productBundleId=\<BUNDLE_ID>&quantity=<QUANTITY>&amount=<AMOUNT>&statuses=<STATUS>&statuses=<STATUS>
Headers
Content-Type: application/json
Authorization: Basic <token>
(note: we will provide you with basic authentication credentials)
Supported query parameters
Parameter | Format | Description |
---|---|---|
platform | String (Mandatory) | This is to identify for which platform the request is initiated. The value for the attribute should be 'SHOP' |
countryCode | String (Mandatory) | The country code of the originating request |
productBundleId | Long (Mandatory) | The primary key of the product bundle which is being bought |
quantity | Integer (Mandatory) | The quantity of product bundle being bought |
amount | BigDecimal (Mandatory) | The amount in the currency of the country code |
statuses | String (Mandatory) | The status of payment method. The value for this attribute can be 'ACTIVE', 'SUSPENDED' |
Response
The API will respond with a JSON object containing an array of payment methods.
Example response
{
"data": {
"groups": [
{
"id": 38,
"name": "Bank Transfer",
"imageLocation": "https://d13ms5efar3wc5.cloudfront.net/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6ImRjODJkMzZjLTRhYTYtNDkwNS05MTgyLTg4MjFiNWY3MTQ0YS5qcGcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
"channels": [
{
"id": 56,
"channelCode": "KUDA_BANK",
"channelName": "Kuda Bank",
"paymentMethod": "BANK_TRANSFER",
"imageLocation": "https://d13ms5efar3wc5.cloudfront.net/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6Ijk1NmU4NGFhLWZkYmItNDkyZi1hMTQzLTZhZjg2NWU0N2IyYy5qcGcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
"displayOrder": 90,
"status": "ACTIVE"
},
{
"id": 59,
"channelCode": "PROVIDUS_BANK",
"channelName": "Providus Bank",
"paymentMethod": "BANK_TRANSFER",
"imageLocation": "https://d13ms5efar3wc5.cloudfront.net/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6ImY5ZmY2MWViLWMyM2EtNDgxNS05OTc0LTVlMjA1MTk4NGI4Yy5qcGcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
"displayOrder": 93,
"status": "ACTIVE"
}
]
},
{
"id": 1,
"name": "Credit / Debit Card",
"imageLocation": "https://d13ms5efar3wc5.cloudfront.net/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6IjJlNTg3YzVmLWFlNWItNGVkYy04ZjIxLTVmNDg1MGViYzQ4MS5qcGcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
"channels": [
{
"id": 2,
"channelCode": "VISA",
"channelName": "Visa",
"paymentMethod": "CARD",
"imageLocation": "https://d13ms5efar3wc5.cloudfront.net/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6InZpc2Euc3ZnLndlYnAiLCJlZGl0cyI6eyJyZXNpemUiOnsid2lkdGgiOjk2fX0sIndlYnAiOnt9fQ==",
"displayOrder": 37,
"status": "ACTIVE"
}
]
}
],
"channels": [
{
"id": 104,
"channelCode": "CARD",
"channelName": "Card",
"paymentMethod": "CARD",
"imageLocation": "https://d13ms5efar3wc5.cloudfront.net/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6IjIzYjk1NWIwLTEwMzctNGE4MS1iNzdmLTlmNWQ4NGMwM2FiNy5qcGcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
"displayOrder": 1,
"status": "ACTIVE"
},
{
"id": 102,
"channelCode": "VERVE",
"channelName": "Verve",
"paymentMethod": "CARD",
"imageLocation": "https://d13ms5efar3wc5.cloudfront.net/eyJidWNrZXQiOiJzdGFnaW5nLWltYWdlcy1jYXJyeTFzdC1wcm9kdWN0cyIsImtleSI6ImZiOTFkYzdhLTA4MWQtNDc2Mi1iM2EyLTA1YzU4N2NiNTZkMy5wbmcud2VicCIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6OTZ9fSwid2VicCI6e319",
"displayOrder": 2,
"status": "ACTIVE"
}
]
}
}
Each payment method in the response contains the following fields:
Field | Format | Description |
---|---|---|
id | String | The unique identifier of the payment method |
name | String | The name of the payment type (e.g., Bank Transfer, Card, etc.) |
imageLocation | String | The URL of the payment type or method's logo image |
channelCode / channelName | String | The code/name of the specific payment method or bank |
displayOrder | String | The order in which payment methods will be displayed |
status | String | Live status of the payment method |
Response Codes
The payment method API may return the following response codes:
200 : The request was successful, and the payment methods were retrieved successfully.
401 : Unauthorized: The API key is missing or invalid.
500 :Internal Server Error: An error occurred on the server while processing the request.
Error Handling
If an error occurs while processing the request, the API will return a JSON response with an appropriate error message and HTTP status code.
Example Error Response
{
"error": "Invalid API key",
"status": 401
}
Rate Limiting
Our payment methods API has rate limiting in place to prevent abuse. The current rate limits are as follows:
Requests per minute (RPM): [XX]
Requests per day (RPD): [XX]
If you exceed the rate limits, the API will return a [429 Too Many Requests status code].
Conclusion
The Payment Methods API allows you to retrieve a list of available payment methods supported by Pay1st. Use the provided GET endpoint to retrieve the payment methods information and include your API key for authentication. Please refer to the response structure and error handling section for details on the expected response format and error handling.