Payments API
Introduction
Using this section you can easily manage your single immediate payments within the toolkit Payments API.
Payment statuses
List of statuses that a payment can have. Fena notifies the user of the API key about each change in the status (except of draft) of the payment via webhook.
| Status | Description |
|---|---|
| Draft | Draft payment which can be processed later via api call |
| Sent | The payment has been sent to the end user and can be paid, |
| Overdue | The payment is marked as overdue, but it behaves exactly as a sent payment does |
| Pending | The payment has been made by the end user and await a status update from the payment provider.In this status it cannot be modified |
| Paid | The payment has been paid (nothing can be changed in this payment) |
| Rejected | The payment has been rejected (nothing can be changed) but the end user can retry to initiate it |
| Cancelled | The payment has been cancelled and cannot be paid anymore |
| Refund started | The payment is being refunded |
| Refund rejected | Refund failed |
| Refunded | Refund successful |
| Partial refund | Partial refund successful |
Sandbox
If you want to see for yourself how our payment flow works you can create a sandbox payment with the sandbox bank account which we've created for you automatically during sign up. You don't have to pass ID verification checks or verify your data, and you can start integrating right away. Please note that sandbox payments don't initiate any real bank transfers so you shouldn't expect any money to actually arrive. In order to test the flow with real funds you have to pass the ID and bank verification first.
Example of usage
Let's see how to create a payment link that can be passed to the end user.
To interact with the API, we will need the ID terminal and the secret terminal that were created when reading this guide. These 2 parameters will be present in the header of almost every request.We will also need to fill in the minimum required data to create a payment. <<<<<<< HEAD
- As a result, the first request to create a draft payment will look like this:
curl -X POST https://epos.apifena.co/open/payments/single/create \
=======
1. As a result, the first request to [create a draft payment](https://epos.api.fena.co/open/payments/single/create-and-process) will look like this:
curl -X POST https://epos.api.fena.co/open/payments/single/create \
main -H "Content-Type: application/json" \ -H "terminal-id: 65c3c12d9404ea7569d66623" \ -H "terminal-secret: 0979a189-706d-49ff-88f8-33992ad049c5" \ -d '{"amount":"1.00", "reference":"test"}'
The response for this will look like this:{ "created":true, "result":{ "id":"65dd0ced68bed03ef618adb0", "amount":"1.00", "currency":"GBP", "createdAt":"2024-02-26T22:13:01.574Z", "isSandbox":true, "status":"draft", "reference":"test", "customerEmailCC":[
],
"notes":[
],
"paymentMethod":"fena_ob_qr",
"attachments":[
],
"bankAccount":{
"id":"63b6aa383e390e2ff15ab7a3",
"name":"Sandbox",
"sortCode":"111111",
"accountNumber":"11111111",
"provider":"other",
"createdAt":"2023-01-05T10:45:12.089Z",
"isSandbox":true,
"isDefault":true,
"status":"verified",
"creationType":"manual"
}
} }
2. Now we can use [process](https://toolkit-docs.fena.co/toolkit-api/payments-module/single-payments/api-requests#tag/Payments/paths/~1payments~1single~1%7Bid%7D~1process/post) request to create payment link that can be given to the end user to pay. To do this, we need to substitute the payment ID received after completing the previous request into the url of the next request instead of {id}
<<<<<<< HEAD
curl -X POST https://epos.apifena.co/open/payments/single/65dd0ced68bed03ef618adb0/process \
curl -X POST https://epos.api.fena.co/open/payments/single/65dd0ced68bed03ef618adb0/process \
main -H "Content-Type: application/json" \ -H "terminal-id: 65c3c12d9404ea7569d66623" \ -H "terminal-secret: 0979a189-706d-49ff-88f8-33992ad049c5" \
This will give us updated payment:
{
"saved":true,
"result":{
"id":"65dd0ced68bed03ef618adb0",
"amount":"1.00",
"currency":"GBP",
"createdAt":"2024-02-26T22:13:01.574Z",
"isSandbox":true,
"status":"sent",
"reference":"test",
"customerEmailCC":[
],
"notes":[
],
"paymentMethod":"fena_ob_qr",
"attachments":[
],
"bankAccount":{
"id":"63b6aa383e390e2ff15ab7a3",
"name":"Sandbox",
"sortCode":"111111",
"accountNumber":"11111111",
"provider":"other",
"createdAt":"2023-01-05T10:45:12.089Z",
"isSandbox":true,
"isDefault":true,
"status":"verified",
"creationType":"manual"
}
<<<<<<< HEAD
"link":"https://epos-sandboxfena.co/pay/?p=gjYyk0DWLBc35yjVRznP",
=======
"link":"https://epos-sandbox.fena.co/pay/?p=gjYyk0DWLBc35yjVRznP",
>>>>>>> main
"qrCodeData":"https://fena-stage.s3.eu-west-2.amazonaws.com/65dd0ced68bed03ef618adb0_qr.png"
}
}
Now the link from the "link" field can be used to initiate payment.
Note: Step 1 and 2 can be combined into 1 create-and-process request.
- After step 2, the payment is ready to be transferred to the client for authorization. You can process this stage in 2 ways
- You can give the client a link or cur code, which are located in the link and cur code fields. After the client proceeds, he will be taken to the payment initiation page, where the client will be able to select the provider with which he wants to make your payment. After selecting a provider, the client will be asked to switch to the payment authorization service of the selected provider
- Generate a link to authorize payment from the provider by sending a request of the following type:
curl -X POST https://epos.api.fena.co/open/payments/single/create \
-H "Content-Type: application/json" \
-d '{"provider":"ob-sandbox-natwest",
"id":"gjYyk0DWLBc35yjVRznP"}'
After the user has authorized the payment, you will be notified about the payment status by a webhook to the url address you specified when creating the API key. The client himself will be redirected to the payment status page, and after that to the page that you specified in the redirect url field of API key