Initiate a payment

This API serves the purpose of initiating a payment request from a customer (Payer). It is typically employed by various applications, such as online web shops, to solicit a payment from a customer. In this process, the customer is prompted to authorize and confirm the transaction on their client-side interface.

Here's a breakdown of how this API is commonly used:

Payment Request Initiation: When an online web shop or a similar application wishes to receive payment from a customer for goods or services, it utilizes this API. It sends a request to the API to initiate the payment process.
Customer Involvement: The customer, who is the intended payer, becomes involved in the process. They are presented with the payment request on their client-side interface, which could be a website, mobile app, or any other platform where they interact with the application.
Transaction Authorization: The customer is prompted to review the details of the payment request, which typically include the payment amount, a description of what they are paying for, and the chosen payment method (e.g., credit card, bank transfer). They are then asked to approve or authorize the transaction.
Client-Side Confirmation: On the customer's client-side interface, they confirm their willingness to proceed with the payment. This confirmation could involve clicking a "Pay" button or taking other appropriate actions to finalize the transaction.
Client-Server Interaction: The client-side confirmation triggers interactions with the server-side component of the application, which may involve sending a confirmation signal or a response back to the server hosting the API.
Payment Processing: With the customer's authorization confirmed, the API then proceeds with the payment processing steps. It communicates with payment gateways or financial institutions to execute the payment transaction securely and efficiently.
Transaction Status Notification: After the payment has been successfully processed, the server may send a notification or confirmation back to both the customer and the application. This notification typically includes details about the transaction status, such as "payment successful."
Error Handling: In the event of any issues or errors during the payment process (e.g., insufficient funds, payment method failure), appropriate error messages are relayed to the customer and the application to provide transparency and guidance on how to address the situation.
Security Measures: Throughout this entire process, robust security measures are implemented to safeguard the customer's sensitive payment data and ensure the secure handling of transactions. This often includes encryption, tokenization, and adherence to security standards.

In summary, this API enables applications like online web shops to initiate payment requests to customers, who are then prompted to confirm and authorize the transaction on their client-side interfaces. It streamlines the payment process, making it convenient and secure for both businesses and customers, while ensuring that payments are processed accurately and transparently.

For the security sake, we need to start generating an access which will be used on payment request

Here below, the API specification to create the access token

POST /v1/tokens HTTP/1.1
Host: kepissasbc.execute-api.eu-west-1.amazonaws.com
Authorization: Basic {base64(wallet_adress:wallet_private_key)}

Create Access Token Sample API Request

curl --location --request POST 'https://kepissasbc.execute-api.eu-west-1.amazonaws.com/v1/tokens' \
--header 'Authorization: Basic base64_encoded_value'

Create Access Token Sample API Response

HTTP 200 OK
{
    "jwt": "eyJhbGciOiJSUzI1NiJ9.eyJhZGRyZXNzIjoiMUdDelQ1NGtBNTRxVmhIWkRZR050S2RFenY4eHVEN0ZwSCIsInN1YiI6IndhbGxldF8yVnQzNUk1WDNvRkdwSUhsa0FZNnJGWkhDNmUiLCJpYXQiOjE2OTY1MzUwMDMsImlzcyI6ImlkLmxpZ2h0cGF5LmlvIiwiZXhwIjoxNjk2NTM4NjAzfQ.aSgQRqlqQQR5CpqfdHE5rlRj__FTjv3ZKQf79IPAbG4-9kJMnmh0_X5vi9ZHS25TqGfK6h7NflwZP6ziL5AxDcuAcj1lHKUYkRlLQSv7_rM2BxuVdAPQdNk2Fu5Kzw-zI8pE794DRtLnGkUyR3vgvaLyPeUcdrJsgscQz2A0l21jsXj1Vbz6qwsVvDluJvpe-Awfklb07c1d42foClkZB1c9pF77rkw6tut8AUrq_7AB7MaX5L650SsKDsCdRahWLSDKk85jpmufah7VY7cIdKBDJAK2xNkGXSFhccezz5321Jkt_suOLwF_fn8gbGi7HiJ6p2R2smAVmuguQJWMVN-T8lwRJtIXLokK2hrN8mCO3PFXDOm_fod774PAz1ZebJb8Ttx42tufsrYDrr2hwJ3-uiF2omAxvAzxM-bvTnejxP-i224kIvTgoC7X0FWaV9W89WbkyQK791xyVu04HPV9Ohr-BlztCgJrR9anu9GJqakg26o4GeYzv79jaa8WuXHTXhcEOjU6mTVMPH1CkWhINVB7cpalIyyXQ0G2FhjCYJXEvJX_NZ_IOWruINfpG5Hlrl_kWg_oOuyWY2ZRV8WCw33pYV1COAbsDNirxn4jyf3WKFL7P6DIcDQNKp4p9vZwBgHO4jGWjVdhkvftmsaJPhusR0ls9N_MOIf94_E"
}

Once the access token create, we can proceed on the Payment Request

POST /v1/payments HTTP/1.1
Host: kepissasbc.execute-api.eu-west-1.amazonaws.com
x-callback-url: https://staging.fnstack.dev/webhooks/light-pay/payments
Content-Type: application/json
Authorization: Bearer access_token
Content-Length: 199
 
{
    "externalId": "string",
    "amount": int,
    "payer": {
        "payerId": "string",
        "payerIdType": "EMAIL | MSISDN"
    },
    "description": "string"
}

Please note that x-callback-url header is not mandatory

Here below, the API specification for payment request

Payment Request Sample API Request

curl --location 'https://kepissasbc.execute-api.eu-west-1.amazonaws.com/v1/payments' \
--header 'x-callback-url: https://staging.fnstack.dev/webhooks/light-pay/payments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
    "externalId": "txn_2WO0catb7yoa8g0r6R1yfsZ3neC",
    "amount": 1000,
    "payer": {
        "payerId": "242067895263",
        "payerIdType": "MSISDN"
    },
    "description": "test"
}'

Payment Request Sample API Response

HTTP 202 ACCEPTED
{
    "paymentId": "payment_2Wd1bUahVTw76DsoLTsYsXnaHgT",
    "externalId": "txn_2WO0catb7yoa8g0r6R1yfsZ3neC",
    "status": "PENDING"
}

Introduction Make Transfer