- 10 Feb 2023
- DarkLight
Direct API Integration
- Updated on 10 Feb 2023
- DarkLight
Payment Flow
For merchants that are not on an e-commerce platform, it is necessary to integrate using the Zenki pay REST API. Before we get into the detail of the integration, let's review the typical flow of a payment:
- The buyer has added the items or services they want to buy in their shopping cart and selects the option 'proceed to payment', 'checkout' or 'checkout' in the merchant portal.
- The merchant requests the buyer's data and delivery address (in case they do not have an account on the merchant's portal or have not previously registered) and shows the payment options available to the buyer.
- The buyer selects the option to pay with crypto using Zenki pay and clicks on the 'pay' button.
- Within the merchant page, the Zenkipay payment window opens where the buyer makes the payment with his cryptocurrency wallet.
- The merchant and the buyer receive a notification from Zenkipay, indicating that the payment is processed correctly.
Integrating commerce with Zenkipay
According to the previous flow, the adjustments you must make in the commerce portal are the following:
- Add the payment button on the checkout screen (Front-end) and implement the call (submit) to the merchant's back-end.
- Develop a service on the merchant's back-end that records order information by calling the Zenkipay API .
- Return the information returned to you by the API when registering the order, and pass it as parameters to open the payment window (modal) of Zenkipay on the screen (Front-End).
- Implement a mechanism to receive the notification of successful payment (Back-end). For this you have 2 options:
- Webhook [Recommended]: With this mechanism you must expose a public REST service so that we notify you when the payment is processed correctly.
- Order status query via API: In this mechanism you must periodically check the status of an order and confirm if it is processed correctly.
- Optionally, invoke the following trade-side API services:
- View trade information
- Shipment registration for tracking
- Shipping status update
- Registration of refunds for an order
1. Add payment button
Check our Best UX/UI practices guide where you can download the images of the available buttons and recommendations to incorporate them into the merchant's site. For your convenience, we have developed libraries for some front end technologies:
If your technology is not in the previous list, you can integrate with Javascript.
2. Record order information
When the buyer is in the payment of the order and indicates that he wishes to make his payment with Zenkipay, the merchant portal must inform Zenkipay of the order information in order to open the payment window.
Authenticate API Client
Zenkipay API is designed on top of REST, so we will find that the URLs are resource-oriented. In addition, HTTP response codes are used to indicate API errors. It is necessary to have a Zenki account, otherwise you will need to register the trade in our main page. To make requests to the Zenkipay API, the following is required:
- Get your access credentials for the Zenkipay API .
- Perform HTTP authentication using the Bearer Token schema on all Zenkipay API calls .
- See the Zenkipay API endpoint detail to authenticate your requests at the following link.
Register the Order
The order information must be registered using the Zenkipay API , it must go in the body of the HTTP request in JSON format.
3. Open the payment modal
The above endpoint call will return the order information along with the zenkiOrderId (Zenkipay-generated unique order identifier) and paymentSignature (Signing payment order information to show modal) fields which will be used to open the payment modal.
4. Receive notification of successful payment
Finally, if the payment was made successfully, you will be informed through a webhook or if you do not configure it, you should consult it periodically by calling the endpoint of consultation of an order.
- See thefull zenkipay API endpoint for get order information.
- See the details of the integration with Zenkipay Webhook.
5. Invoke additional endpoints
The Zenkipay API has additional services to automate some of the tasks that merchant operators perform in our merchant portal. You can check the detail of the endpoints below:
- Check merchant information: Used to obtain the current configuration of the trade.
- Shipment record for tracking: Used to record one or more shipment tracking numbers by order number.
- Shipping Status Update: Used to update the delivery status of an order.
- Refunds register for an order: Used to register one or more refunds per order number.
Test and Productive Setup
During the enrollment process you will be provided with API credentials (client_id and client_secret) to perform your tests. At the end of your trial you will be provided again for your production environment.
- Do not share your keys with third parties or copy them to public storage media.