Use this API to list the supported payment methods provided by Pay1st
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.
Pre Requisites
- An access token needs to be generated in order to use this API (see Authentication - Generate Access Token)
API Description
Headers
| Header | Description/Value |
|---|---|
| AccessToken | This is the Access Tokenfield returned from the Authentication - Generate Access Token response. This should be in the format Bearer <AccessToken> |
| Content-Type | application/vnd.carry1st.payments.paymentchannel+json |
URL Format
To retrieve a list of available payment methods, make a GET request to the following endpoint:
GET /api/pay1st/payments/methods?countryCode=<COUNTRY_CODE>List of URL Query Parameters
| Parameter | Format | Mandatory | Description |
|---|---|---|---|
| countryCode | String | Y | The country code to list payment methods for. |
Response
The API will respond with a JSON object containing an array of payment methods.
Example Successful Response
{
"data": {
"groups": [
{
"id": 1,
"name": "Credit / Debit Card",
"imageLocation": "visa_mastercard.svg",
"channels": [
{
"id": 2,
"paymentOption": {
"id": 3,
"name": "Paystack",
"code": "PAYSTACK",
"status": "ACTIVE"
},
"channel": {
"id": 8,
"name": "Visa",
"code": "VISA",
"paymentMethod": "CARD",
"status": "ACTIVE",
"channelCode": "VI",
"imageLocation": "visa.svg"
},
"paymentMethodType": {
"id": 5,
"name": "Basic",
"code": "BASIC",
"requiredParameters": "{\"personalInfo\":{\"firstName\":{\"dataType\":\"string\"},\"lastName\":{\"dataType\":\"string\"},\"email\":{\"dataType\":\"string\"},\"phoneNumber\":{\"dataType\":\"string\"}}}",
"canSaveCredentials": false,
"canEditCredential": false,
"status": "ACTIVE"
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 36,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 1,
"whaleCustomerExempted": false
}
]
},
{
"id": 45,
"name": "PAGA Group",
"imageLocation": "b36bd980-7f10-4375-a31c-fbd315298c1b.png",
"channels": [
{
"id": 173,
"paymentOption": {
"id": 9,
"name": "Paga",
"code": "PAGA",
"status": "ACTIVE"
},
"channel": {
"id": 150,
"name": "Paga Wallet V2",
"code": "PAGA_WALLET_V2",
"paymentMethod": "PAGA_WALLET_V2",
"status": "ACTIVE",
"imageLocation": "3befbe6b-9185-44e4-bbe5-dc0aa65b84dc.png"
},
"paymentMethodType": {
"id": 9,
"name": "Basic Phone",
"code": "BASIC_PHONE",
"requiredParameters": "{\"personalInfo\":{\"firstName\":{\"dataType\":\"string\"},\"lastName\":{\"dataType\":\"string\"},\"email\":{\"dataType\":\"string\"},\"phoneNumber\":{\"dataType\":\"string\"}},\"paymentInfo\":{\"phoneNumber\":{\"dataType\":\"string\"}}}",
"canSaveCredentials": true,
"canEditCredential": true,
"status": "ACTIVE"
},
"countryCodes": [
"NG",
"ZA",
],
"currencyCode": "NGN",
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 164,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 1
},
{
"id": 196,
"paymentOption": {
"id": 9,
"name": "Paga",
"code": "PAGA",
"status": "ACTIVE"
},
"channel": {
"id": 154,
"name": "USSD",
"code": "USSD_BANK_TRANSFER",
"paymentMethod": "USSD_BANK_TRANSFER",
"status": "ACTIVE",
"channelCode": ""
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 184,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 1
}
]
},
{
"id": 37,
"name": "Nigeria banks",
"imageLocation": "c0847bd7-a01b-4968-a4aa-ee4f5b2c8cd4.png",
"channels": [
{
"id": 92,
"paymentOption": {
"id": 3,
"name": "Paystack",
"code": "PAYSTACK",
"status": "ACTIVE"
},
"channel": {
"id": 48,
"name": "Kuda Bank",
"code": "KUDA_BANK",
"paymentMethod": "BANK_TRANSFER",
"status": "ACTIVE",
"channelCode": "50211",
"imageLocation": "7988e7b5-587e-459e-9cd3-57bb753b60c8.png"
},
"paymentMethodType": {
"id": 2,
"name": "Kuda Bank",
"code": "KUDA_BANK",
"requiredParameters": "{\"personalInfo\":{\"firstName\":{\"dataType\":\"string\"},\"lastName\":{\"dataType\":\"string\"},\"email\":{\"dataType\":\"string\"},\"phoneNumber\":{\"dataType\":\"string\"}},\"paymentInfo\":{\"phoneNumber\":{\"dataType\":\"string\"}}}",
"canSaveCredentials": true,
"canEditCredential": true,
"status": "ACTIVE"
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 119,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 1,
"maxChargeAmount": 15000
}
]
}
],
"channels": [
{
"id": 161,
"paymentOption": {
"id": 22,
"name": "Opay",
"code": "OPAY",
"status": "ACTIVE"
},
"channel": {
"id": 131,
"name": "Opay Wallet",
"code": "OPAY_WALLET",
"paymentMethod": "OPAY_WALLET",
"status": "ACTIVE",
"imageLocation": "66fdef47-169e-4f64-8df6-8bd6b9bd47d9.png"
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"platforms": [
"SHOP"
],
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 152,
"refundable": false,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 3,
"maxChargeAmount": 30000
},
{
"id": 101,
"paymentOption": {
"id": 14,
"name": "Chipper",
"code": "CHIPPER",
"status": "ACTIVE"
},
"channel": {
"id": 95,
"name": "Chipper Nigeria",
"code": "CHIPPER_NIGERIA",
"paymentMethod": "CHIPPER_NIGERIA",
"status": "ACTIVE",
"imageLocation": "e0f0ddcf-ef61-4b4f-ae9c-0895b8c8dcd6.png"
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"platforms": [
"WEB",
"SHOP"
],
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 128,
"refundable": false,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 1
},
{
"id": 153,
"paymentOption": {
"id": 3,
"name": "Paystack",
"code": "PAYSTACK",
"status": "ACTIVE"
},
"channel": {
"id": 128,
"name": "Verve",
"code": "VERVE",
"paymentMethod": "CARD",
"status": "ACTIVE",
"imageLocation": "9c23b8e4-c20c-4612-a0f3-9cb6d01db5ee.png"
},
"paymentMethodType": {
"id": 10,
"name": "Paystack card",
"code": "PAYSTACK_CARD",
"requiredParameters": "{\"personalInfo\":{\"firstName\":{\"dataType\":\"string\"},\"lastName\":{\"dataType\":\"string\"},\"email\":{\"dataType\":\"string\"},\"phoneNumber\":{\"dataType\":\"string\"}},\"paymentInfo\":{\"cardNumber\":{\"dataType\":\"string\"},\"expiryMonth\":{\"dataType\":\"string\"},\"expiryYear\":{\"dataType\":\"string\"}}}",
"canSaveCredentials": true,
"canEditCredential": false,
"status": "ACTIVE"
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"platforms": [
"WEB",
"AND",
"SHOP",
"IOS"
],
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 14,
"minChargeAmount": 1,
"whaleCustomerExempted": false
},
{
"id": 186,
"paymentOption": {
"id": 24,
"name": "PalmPay",
"code": "PALMPAY",
"status": "ACTIVE"
},
"channel": {
"id": 74,
"name": "PalmPay",
"code": "PALM_PAY",
"paymentMethod": "BANK_TRANSFER",
"status": "ACTIVE",
"channelCode": "999991",
"imageLocation": "94d4e85e-5637-4086-974f-f4e3727c4f07.png"
},
"paymentMethodType": {
"id": 5,
"name": "Basic",
"code": "BASIC",
"requiredParameters": "{\"personalInfo\":{\"firstName\":{\"dataType\":\"string\"},\"lastName\":{\"dataType\":\"string\"},\"email\":{\"dataType\":\"string\"},\"phoneNumber\":{\"dataType\":\"string\"}}}",
"canSaveCredentials": false,
"canEditCredential": false,
"status": "ACTIVE"
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"platforms": [
"WEB",
"SHOP_UAT",
"AND",
"SHOP",
"IOS"
],
"localExchangeRate": 1,
"authorizationUrl": "https://h5-daily.palmpay.app/h5-checkout/inner?broswerSource=Internal&countryCode=NG&appId=L240927093144197211431",
"status": "ACTIVE",
"displayOrder": 5,
"refundable": false,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 1,
"integrationType": "PARTNER_HOSTED"
},
{
"id": 158,
"paymentOption": {
"id": 20,
"name": "dLocal",
"code": "DLOCAL",
"status": "ACTIVE"
},
"channel": {
"id": 130,
"name": "Opay QR",
"code": "OPAY_QR",
"paymentMethod": "OPAY_QR",
"status": "ACTIVE",
"imageLocation": "8eab25d8-8cd4-475d-81d9-f74c7fe3a1c1.png"
},
"countryCodes": [
"NG"
],
"currencyCode": "NGN",
"platforms": [
"SHOP"
],
"localExchangeRate": 1,
"authorizationUrl": "",
"status": "ACTIVE",
"displayOrder": 149,
"refundable": false,
"refundNote": "",
"detailedRefundNote": "",
"minChargeAmount": 100
}
]
}
}The response contains an array of (Payment) Groups and an array of (Payment) Channels. (Payment) Groups are also composed of (Payment) Channels.
Group Fields
| Name | Type | Description |
|---|---|---|
| id | Integer | The identifier of the Payment Group |
| name | String | The name of the Payment Group |
| imageLocation | String | The image location for the Payment Group logo |
| channels | Array | List of Channel Objects (see Channel Fields) |
Channels Fields
Note: This is the response of the Channels Array. This should not be confused with the Channel object
| Name | Type | Description |
|---|---|---|
| id | Integer | The channel identifier |
| paymentOption | Object | Represents the payment gateway that is used for the channel |
| channel | Object | Represents data about the payment channel |
| paymentMethodType | Object | Provides metadata about the payment method to facilitate seamless payments for the user. |
| countryCodes | Array of Strings | List of Country Codes. Each country code is represented in (ISO-3166) Alpha-2 form |
| currencyCode | String | Currency Code |
| platforms | Array of Strings | List of Platforms in which this channel is supported. For Pay1st Integrations, only WEB values represent valid channels |
| localExchangeRate | Integer | The local exchange rate that is used for this payment channel |
| authorizationUrl | String | The authorization URL used by the channel |
| status | String | The status of the channel. Valid values are ACTIVE, SUSPENDED, DELETED |
| displayOrder | Integer | An integer representing the preferred display order of the channel |
| refundNote | String | The default note summary that is used when issuing refunds |
| detailedRefundNote | String | A more detailed note summary that is used when issuing refunds |
| minChargeAmount | Integer | The minimum Payment amount that is required by the PSP in order to make a successful Payment |
| whaleCustomerExempted | Boolean | A flag that indicates whether large purchasers are exempted from any Payment velocity limits |
| maxChargeAmount | Integer | The maximum Payment amount that is allowed by the PSP in order to make a successful Payment |
| refundable | Boolean | A flag to indicate whether this payment method supports refunds |
| integrationType | String | This is an indicator for the type of PSP integration. Possible values are S2S and PARTNER_HOSTED. Partner hosted integration types typically involve redirects to the PSP domain |
(Payment) Channel Fields
| Name | Type | Description |
|---|---|---|
| id | Integer | The numeric identifier of the Payment Channel |
| name | String | The display name of the Payment Channel |
| code | String | The unique code of the Payment Channel |
| paymentMethod | String | Represents the type of Payment Method that the Payment Channel represents |
| status | String | This is the status of the Channel |
| channelCode | String | This is the unique code for the Channel |
| imageLocation | String | This is a string that points to an image name. This is typically the logo or symbol that represents the Payment Channel |
Payment Method Type Fields
| Name | Type | Description |
|---|---|---|
| id | Integer | The numeric identifier of the Payment Method Type |
| name | String | The display name of the Payment Method Type |
| code | String | The unique code of the Payment Method Type |
| requiredParameters | String | This contains a JSON object in raw string format that details the required parameters for the payment method type |
| canSaveCredentials | Boolean | A flag to indicate that credentials can be saved |
| canEditCredential | Boolean | A flag to indicate that credentials can be edited for future Payments |
| status | String | The status of the channel. Valid values are ACTIVE, SUSPENDED, DELETED |
HTTP Response Codes
The List Payment Method API may return the following HTTP Response Codes:
| HTTP Status Code | Name | Description |
|---|---|---|
| 200 | Success | This indicates that the request has been successful |
| 400 | Bad Request | The country code could be invalid or missing from the request |
| 401 | Unauthorized | The Access Token might be missing or invalid (see Authentication - Generate Access Token) |
| 403 | Forbidden | The credentials provided might not have access to the resources required |
Error Handling
See Handling Error Codes for more details on handling error responses.