API Integration

The Payguru Cash Payments and Bank Transfer API Integration is a "fintech solution" enabling merchants to accept instant payments from their customers via bank transfers using dedicated Payguru Bank accounts, to query the Payguru Platform with the "payment notifications" submitted by their customers and to import, register and recognize all the payments into their financial system through an auto-matching algorithm.

The components of this API facilitate the technical communications between Payguru Platforms and Merchant Systems throughout the payment process detailed below.

  • The customer selects the "Cash Payment and Money Transfer" option in the check-out phase of the purchasing process on the merchant's web site.

  • On this page, the merchant shows the customer the corresponding order code (order) for the particular purchase and the account numbers of Payguru.

  • The customer sends the money to the his/her chosen Payguru bank account and through any banking channels he/she prefers (ATMs, Digital and Mobile Banking Channels, Bank Branches etc). He/she enters the order code into the "description" field in the corresponding banking interfaces.

  • Payguru receives the notification of the instalment made into its bank accounts through the integration with the banking infrastructure. Payguru detects the merchant with whom the payment has been made by matching the order code received within the bank notification (as a value in description field) with the merchant configurations and merchant records in its system. Payguru sends the payment notification to the merchant through the API integration between Payguru and the merchant.

  • In the cases where the order code Payguru receives through the bank integrations does not match with any of the registered transaction in the payment platform, Payguru holds the payment amount on protected accounts. The customer needs to make a manual payment notification through the website of the merchant.

  • After the customer makes the necessary manual notification through the merchant's web site, the merchant queries the PAYGURU platform for the payment of the customer with the given parameters.

  • Payguru matches the payment information received from the merchant with the records in its system. Once the relevant payment record is found, Payguru sends merchant the necessary payment notification and finalizes the payment process.

Merchant is expected to develop 2 customer interface in order to finalize the integration:

  1. The interface where the order code will be shared with the customer (usually in the check-out phase).
  2. The interface where the customer can manually create a payment notificaiton for the payments that are not matched in the Payguru Platform.

All the other components of the API are presented below in the relevant sub-section together with the code samples.

1. Token

It is a piece of information that is created by the Payguru Platform

  • dedicated for a single merchant
  • valid for a limited period

and enables the merchant to access the Payguru Platform for queries and notifications. It is used in all the integration steps as an authentication parameter for the merchant.

2. Notifications

Notifications are the basic web services for the Payguru API integration. They are used to transmit the information to the merchant for all the "accepted payments" by Payguru Platform. Merchant receives all the information about payments by their customers through those notifications.

3. Transaction

Those are the services that can be used by the merchant in order to "query" the Payguru Platform for a single transaction or for a group of transaction with a certain criteria. The same service group is used by the merchant in order to send the "order completed" notification to the Payguru Platform.

4. Bank

It is a query service used by the merchant to dynamically retrieve the bank and bank account list that are integrated to the Cash Payments and Bank Transfer Service of Payguru. The service doesn't require any merchant authentication.

5. Order Lookup

Those are the services to be used in the scenarios when the Merchant wants to share a separate shopping order in its system as an identifier for the payment. Merchant may trigger an order code generation process in the Payguru Platform for each shopping order in its system or may push its shopping order as an order code by using those services. Those services bring flexibility to the merchant in order to create a smooth shopping and purchasing experience for their customers by providing them a single "code" for both the payment and purchase.

6. Refund

Those are the services creating refunds for the payments made through the Payguru Platform when necessary. All the refund process should be initiated by the merchant through the services below using the order code as the major identifier for the entire process. .

7. Non-Automatic Order Matching Services

Those are the methods for the "manual payment notification process" in order to collect more information from the customer if the order code does not match with any payment records in the Payguru Platform. The merchant collects the necessary information and parameters from the customer through an interface provided on its own web site. The parameters are used as "search criteria" in the following services querying the Payguru Platform to find and match the relevant record.

8. Status Code

All the status codes used in the notifications and service responses can be found in the tables under the corresponding links below.