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 Token`field 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.