Payments
Introduction
Now that you have an access token, you can use this to create, cancel, and reverse payments, using the applicable endpoint.
Payment
When creating a payment, a unique payment ID will be returned. This payment ID is what you will use in the client SDK.
Payment status
Payments start off in a Pending state. If the user pays for the payment using the client sdk, the amount for the payment will be moved from the user's wallet, to your merchant's wallet and the payment will then switch to the Paid status. A payment that does not go into the Paid state within four days of its creation will expire, after which it will go into the Expired state. A payment's status can change to Canceled at Sticitt's discretion.
Payments that are not in the Expired or Canceled state should be stored, and the same payment ID should be returned to the client sdk's to prevent creating duplicate payments.
Expired and Canceled payments, should be forgotten and a new payment should be created if the user tries to pay again.
Status | Code |
|---|---|
Pending | 0 |
Authorized | 1 |
Paid | 2 |
Expired | 3 |
Canceled | 4 |
Reversed | 5 |
- Note
The `Authorized` state is deprecated, and is no longer in use.
Create payment endpoint
You need:
Your
merchant idin order to create paymentsYour access token in order to interact with the host-to-host API
Host url
To create a payment make a request to the following endpoint.
Access tokens should be appended to API calls using the HTTP header.
http-header | Authorization: Bearer your-access-token |
Create payment
POST | /v1/payment |
Request body
merchantID | Required: Your unique merchantID will be provided separately |
amount | Required: Payment amount in cents min 100 max 50 000 000 |
reference | Required: A machine readable reference for recon purposes to track what is being paid. Like a control account or project ID |
debtorReference | Optional: A machine readable reference for recon purposes to track who is being paid for. Like a debtor account or person ID |
description | Optional: A human readable description used for displaying on user interfaces. Like a project name and debtor name combined (MAX 256 char) |
project | Optional: A human readable name to track what is being paid for. Like a control account or project name (MAX 256 char |
debtor | Optional: A human readable name to track who is being paid for. Like a debtor account or person name (MAX 256 char) |
paymentSuccessfulReturnUrl | Optional: Enter an HTTPS URL to redirect users after a successful payment through the Sticitt Web SDK (Max: 512 characters). |
Possible Responses
Status Code | Description | Reason |
|---|---|---|
200 | Success | |
400 | Bad Request | At least one of the arguments are invalid |
401 | Unauthorized | Token invalid, expired or missing |
404 | Merchant not found | The MerchantID provided could not be found |
Successful response body
Field | Description |
|---|---|
paymentID | Generated unique ID. Keep this for reference to the payment |
amount | Amount in cents of payment |
createdAt | Timestamp when payment was created |
authorizedAt | Nullable timestamp when payment was authorized |
expiredAt | Nullable timestamp when the payment was expired |
paidAt | Nullable timestamp when the payment was paid |
clientID | API ID assigned to you |
merchantID | Your unique MerchantID. Will be provided separately |
merchantName | Your Merchant name |
merchantAccountReference | Your merchant account reference |
status | The payment |
walletID | Nullable reference to wallet who authorized or paid |
cardPaymentFee | Fee in cents which user will pay if using a credit or debit card |
reference | String project reference used to track the payment (MAX 50 char) |
debtorReference | Nullable string debtor reference used to track the payment (MAX 64 char) |
description | Nullable string used to describe the payment to a user (MAX 256 char) |
project | Nullable string with a project name used to track the payment (MAX 256 char) |
debtor | Nullable string with a debtor name used to track the payment (MAX 256 char) |