Direct API Integration
  • 10 Feb 2023
  • Dark

Direct API Integration

  • Dark

Article Summary

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:

  1. 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.
  2. 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.
  3. The buyer selects the option to pay with crypto using Zenki pay and clicks on the 'pay' button.
  4. Within the merchant page, the Zenkipay payment window opens where the buyer makes the payment with his cryptocurrency wallet.
  5. 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:

Flujo de pago Zenkipay

  1. Add the payment button on the checkout screen (Front-end) and implement the call (submit) to the merchant's back-end.
  2. Develop a service on the merchant's back-end that records order information by calling the Zenkipay API .
  3. 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).
  4. Implement a mechanism to receive the notification of successful payment (Back-end). For this you have 2 options:
    1. Webhook [Recommended]: With this mechanism you must expose a public REST service so that we notify you when the payment is processed correctly.
    2. Order status query via API: In this mechanism you must periodically check the status of an order and confirm if it is processed correctly.
  5. Optionally, invoke the following trade-side API services:
    1. View trade information
    2. Shipment registration for tracking
    3. Shipping status update
    4. 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 .
šŸ’”For the request of the generation of the Token, the access key is the username and the secret key is the equivalent of the password.

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.

See the full Zenkipay API endpoint to register an order at the link below.

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.

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:

  1. Check merchant information: Used to obtain the current configuration of the trade.
  2. Shipment record for tracking: Used to record one or more shipment tracking numbers by order number.
  3. Shipping Status Update: Used to update the delivery status of an order.
  4. 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.

- Make sure you correctly differentiate test and production keys.
- Do not share your keys with third parties or copy them to public storage media.

Was this article helpful?