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.