Optionally used in Gateway Integration

Overview

The Payment Methods API allows retrieval of 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 Pay1st payment methods to be shown on the Pay1st Partner’s frontend screens.

API Description

Headers

Header	Description/Value
Content-Type	`application/json`
Authorization	`Basic <token>`

Note: The basic auth credentials will need to be provided by the Pay1st Implementation Manager before using this API.

URL Format

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>

List of URL 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

HTTP Response Codes

The payment method API may return the following HTTP Response Codes:

200 - Success
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.

Valid HTTP Failure Status Codes:

401 - Unauthorized
- The API key is missing or invalid.

HTTP Response Body:

{  
  "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): 10
Requests per day (RPD): 10000

If the rate limits are exceeded, the API will return a [429 Too Many Requests status code]