Payments
Receive Payments using SP Pay RESTful API.
A key part of every business, is payments. For any service you provide, you need to be able to receive payments.
To receive payments via API, you will need to make at least one of the two API calls below.
- Initiate Payment - This call validates and creates a payment request. However, to prevent fraudulent payment requests, customers who have not used your web / mobile application in while, will receive an OTP (One Time Password) to authenticate the request.This API call, will return one of two things.
- If the customer is an existing customer, or has authenticated a request from your app recently, a validation prompt will be immediately triggered for approval and you will receive the transaction details as a response.
- Otherwise, a one time password will be sent to the customer via SMS for approval, and you will receive the OTP_ID which you will use in the Confirm Payment Call, along with the OTP code.
- Submit OTP - This API call is only required, if an OTP is generated in the Initiate Payment Call.
Initiate a Payment
POST - Initiate Payment
Request to generate an API Token for subsequent requests as a Bearer Token.
Endpoint
{{sppay-host}}/v1/api/payments/initiate
Request
{
"receive_account_no": "1000",
"amount": 2,
"payee": {
"email": "[email protected]",
"account": {
"code": "MTN",
"number": "0597018036"
}
},
"callback_url": "{{sppay-host}}/v1/sp-pay/webhook"
}
Your SP Pay account number to which the collection should be received.
Amount to be collected.
Object of payee.
Email address of payee.
Account object of payee.
Payee account code.
Payee account number.
URL to which final transaction status and information will be sent to.
Response
{
"status": "Success",
"message": "Transaction submitted for processing. Please prompt customer to validate on third party.",
"transaction": {
"id": 9,
"reference": "ZEMQDWUYJ0",
"external_reference": "",
"primary": 1,
"type_code": "TPSD",
"currency": "GHS",
"amount": "2.00",
"debit_account_name": "MICHAEL EKOW SELBY",
"debit_account_no": "0271777557",
"debit_account_institution_code": "ATL",
"credit_account_name": "SP Pay Cedi Account 1",
"credit_account_no": "1000",
"credit_account_institution_code": "SPP",
"status": 3,
"status_message": "Pending debit completion via script",
"created_at": "Fri, 15 Mar 2024 07:20:18 GMT",
"updated_at": "Fri, 15 Mar 2024 07:20:21 GMT",
"charge": {
"id": 10,
"reference": "ZEMQDWUYJ0",
"external_reference": "",
"primary": 0,
"type_code": "CHRG",
"currency": "GHS",
"amount": "0.04",
"debit_account_name": "MICHAEL EKOW SELBY",
"debit_account_no": "0271777557",
"debit_account_institution_code": "ATL",
"credit_account_name": "SP Pay GHS Suspense Account",
"credit_account_no": "101",
"credit_account_institution_code": "SPP",
"status": 1,
"status_message": "Created. Pending submission",
"created_at": "Fri, 15 Mar 2024 07:20:21 GMT",
"updated_at": "Fri, 15 Mar 2024 07:20:21 GMT",
"payment_category": null,
"pending_actions": []
},
"initiator_id": 1,
"payment_category": null,
"pending_actions": [
{
"id": 2,
"transaction_reference": "ZEMQDWUYJ0",
"action_code": "complete_debit_via_external_script",
"action_reference": "81fe46792fbc47319497cbf9b10da081",
"internal_action_link": "https://www.sppay.dev/pay/ZEMQDWUYJ0",
"external_action_link": null,
"is_completed": 0,
"created_at": "2024-03-15T07:20:21.000000Z",
"updated_at": "2024-03-15T07:20:21.000000Z"
}
]
}
}
Status of API request. success for a successful request and error for an unsuccessful request.
Status message of submitted transaction if succcessful or error message of API request if unsuccessful.
Object of generated transaction if successful.
Unique ID of transaction.
System generated reference of transaction.
User provided reference which will be sent to recipient via SMS.
Flag to indicate whether transaction is a primary transaction or secondary transaction. 1 for primary and 0 for secondary. Secondary transactions are transactions that are generated by system based on certain conditions. E.g. Tax and Charge transactions.
Type code of the debit account.
Currency code of the credit amount.
Amount credited to credit account. This is always in the currency of the credit account.
Name on the debit account.
Account number of the debit account.
Institution code of the debit account.
Name on the credit account.
Account number of the credit account.
Insitution code of the debit account
Status ID of the transaction.
Status message of the transaction.
Time the transaction was created.
Time the transaction wass last updated.
Object of the charge transaction. The structure is identical to the transaction object for which it is a part of. It is only returned if a charge exists.
Object of the tax transaction. The structure is identical to the transaction object for which it is a part of. It is only returned if a tax exists.
ID of the user who created or submitted the transaction.
Object of payment category if a payment category is applied.
Array of pending actions.
Submit OTP ( only when required )
POST - Submit OTP
Request to submit OTP required to complete a transaction.
Endpoint
{{sppay-host}}/v1/api/payments/otp/submit
Request
{
"otp" : "486110",
"transaction_reference": "JACGOURQFB",
}
Grant type your application requires. Set value to password.
A unique ID given to every API accessing user. This is generated when creating API Access for a user.
Response
{
"status": "Success",
"message": "Transaction submitted for processing. Please prompt customer to validate on third party.",
"transaction": {
"id": 6,
"reference": "TFR96E4GH2",
"external_reference": "",
"primary": 1,
"type_code": "TPSD",
"currency": "GHS",
"amount": "2.00",
"debit_account_name": "MICHAEL EKOW SELBY",
"debit_account_no": "0597018036",
"debit_account_institution_code": "MTN",
"credit_account_name": "SP Pay Cedi Account 1",
"credit_account_no": "1000",
"credit_account_institution_code": "SPP",
"status": 3,
"status_message": "Charge attempted",
"created_at": "Fri, 15 Mar 2024 07:18:39 GMT",
"updated_at": "Fri, 15 Mar 2024 07:18:41 GMT",
"charge": {
"id": 7,
"reference": "TFR96E4GH2",
"external_reference": "",
"primary": 0,
"type_code": "CHRG",
"currency": "GHS",
"amount": "0.04",
"debit_account_name": "MICHAEL EKOW SELBY",
"debit_account_no": "0597018036",
"debit_account_institution_code": "MTN",
"credit_account_name": "SP Pay GHS Suspense Account",
"credit_account_no": "101",
"credit_account_institution_code": "SPP",
"status": 1,
"status_message": "Created. Pending submission",
"created_at": "Fri, 15 Mar 2024 07:18:41 GMT",
"updated_at": "Fri, 15 Mar 2024 07:18:41 GMT",
"payment_category": null,
"pending_actions": []
},
"initiator_id": 1,
"payment_category": null,
"pending_actions": []
}
Status of API request. success for a successful request and error for an unsuccessful request.
Status message of submitted transaction if succcessful or error message of API request if unsuccessful.
Object of generated transaction if successful.
Unique ID of transaction.
System generated reference of transaction.
User provided reference which will be sent to recipient via SMS.
Flag to indicate whether transaction is a primary transaction or secondary transaction. 1 for primary and 0 for secondary. Secondary transactions are transactions that are generated by system based on certain conditions. E.g. Tax and Charge transactions.
Type code of the debit account.
Currency code of the credit amount.
Amount credited to credit account. This is always in the currency of the credit account.
Name on the debit account.
Account number of the debit account.
Institution code of the debit account.
Name on the credit account.
Account number of the credit account.
Insitution code of the debit account
Status ID of the transaction.
Status message of the transaction.
Time the transaction was created.
Time the transaction wass last updated.
Object of the charge transaction. The structure is identical to the transaction object for which it is a part of. It is only returned if a charge exists.
Object of the tax transaction. The structure is identical to the transaction object for which it is a part of. It is only returned if a tax exists.
ID of the user who created or submitted the transaction.
Object of payment category if a payment category is applied.
Array of pending actions.
ID of pending action record.
Transaction reference to which this pending action is tied to.
Unique code assigned to the specific action required to be taken.
Unique reference assigned to the specific action required to be taken.
SP Pay link to complete the action if required.
External link to complete the action if required
Flag to indicated if action of completed or not. 0 for pending, 1 for completed.
Time which this pending action was created
Time which this pending action was last updated.