Payment Creation API

This section describes the Payment Creation API which allows users to click on a PAY button in merchant system and get redirected to Paylican Payment Gateway to proceed with payment. This flow does not necessitate merchant's clients to access Paylican Invoice System.

Methods and Endpoints

Get Access Token

• HTTP Method: POST
• URL: {{Keycloak URL}}
• Header: 'Content-Type: application/x-www-form-urlencoded'
• Request Body:

'username=*****' 
'password=*********' 
'grant_type=password' 
'client_id=invoice-system-client'

Create Payment

• HTTP Method: POST
• URL and Endpoint: {{Payment URL}}/api/v1/payment
• Request Body *please see sample codes below

Request body

{
  "amount": 5100.00,
  "type": "XYZ",
  "customerCode": "ABC123",
  "merchantReference": "REF-1234",
  "redirectionUrl": "https://merchant-url.com/",
  "itemName": "Item name",
  "beneficiaryCode": "20",
  "additionalFields": [
    {
      "code": "documentNo",
      "value": "TST1201901260"
    },
    {
      "code": "documentDate",
      "value": "2018-01-03Z"
    },
    {
      "code": "documentReference",
      "value": "LIC201900001430"
    }
  ]
}

Response body

{
  "invoiceId": "XYZ2024-ade08",
  "merchantReference": "REF-1234"
}

Payment object

Parameter Name	Data Type	Description
amount	bigDecimal	Amount to be paid
type	String	Payment Type
customerCode	String	The customer's code that is billed and has to do the payment.
merchantReference	String	Merchant internal reference of the document associated to the Payment.
itemName	String	Item for what the payment is done.
beneficiaryCode	String	Beneficiary code
redirectionUrl	String	Redirection URL after success payment process. Must not exceed 900 characters.
additionalFields	Array	Meta information which could be send during callback webhook process

Redirect to Payment page

• HTTP Method redirection: GET
• URL and Endpoint: {{Keykloak URL}}/auth/realms/PGW/protocol/openid-connect/auth?client_id=invoice-system-client&redirect_uri={{Payment URL}}/api/v1/pay/{type}/{merchantReference}/{invoiceID}

Arguments

Parameter Name	Data Type	Description
type	String	Payment Type
merchantReference	String	Merchant internal reference of the document associated to the Payment.
invoiceId	String	Response from 1st request

Webhook Notification

Webhooks are the notifications that are sent when the payment is executed in the system.

Main field objects

Parameter Name	Data Type	Description
id	Long	Webhook ID automatically generated by system at execution of webhook.
type	String	Invoice paid, invoice created, invoice viewed
data.id	String	Invoice ID
data.status	String	Invoice status
data.totalAmount	bigDecimal	Total amount to paid for the invoice.
data.documentNo	String	Merchant reference
data.paymentNo	String	Transaction reference
data.paymentDate	ZonedDateTime	Date of the payment execution
data.paymentMode	String	CASH, DIRECT_PAYMENT, MOBILE_MONEY
data.collector	String	Bank that processed the transaction
data.bankCode	String	Bank that processed the transaction
createdAt	ZonedDateTime	Webhook sending time
pendingWebhooks	Integer	The difference between Maximum retry attempts and the number of calls already executed.

Additional Field objects

Parameter Name	Data Type	Mandatory/ optional	Description
code	String	optional	Additional Field code
value	String	optional	Additional Field value

Webhook Notification Body example

Payment initiated

{
 "createdAt":"2024-03-28T14:32:47.238686329Z",
 "data": {
   "additionalFields": [],
   "bankCode": "GNAFRI",
   "collector": "GNAFRI",
   "documentNo": "REF-178T876",
   "id": "ABC2024-123",
   "paymentDate": "2024-03-28T14:34:30.155101Z",
   "paymentMode": "BANK_TRANSFER",
   "paymentNo": "gup87876f",
   "status": "UNPAID",
   "totalAmount": 100
 },
 "id": 41768,
 "pendingWebhooks":2,
 "type": "invoice.payment_initiated"
}

Payment Error

{
  "createdAt":"2024-03-28T14:32:47.238686329Z",
  "data": {
    "additionalFields": [],
    "documentNo": "REF-178T876",
    "id": "ABC2024-123",
    "paymentNo": "gup87876f",
    "status": "UNPAID",
    "totalAmount": 100
  },
  "id": 41768,
  "pendingWebhooks":2,
  "type": "invoice.payment_error"
}

Payment Executed

{
 "createdAt":"2024-03-28T14:32:47.238686329Z",
 "data": {
   "additionalFields": [],
   "bankCode": "GNAFRI",
   "collector": "GNAFRI",
   "documentNo": "REF-178T876",
   "id": "ABC2024-123",
   "paymentDate": "2024-03-28T14:34:30.155101Z",
   "paymentMode": "BANK_TRANSFER",
   "paymentNo": "gup87876f",
   "status": "PAID",
   "totalAmount": 100
 },
 "id": 41768,
 "pendingWebhooks":2,
 "type": "invoice.payment_initiated"
}

Payment rejected

{
 "createdAt":"2024-03-28T14:32:47.238686329Z",
 "data": {
   "additionalFields": [],
   "documentNo": "REF-178T876",
   "id": "ABC2024-123",
   "paymentNo": "gup87876f",
   "status": "UNPAID",
   "totalAmount": 100
 },
 "id": 41768,
 "pendingWebhooks":2,
 "type": "invoice.payment_rejected"
}

Responses Status Codes (Code HTTP)

The response body is optional and it will be logged in Database if sent.

Code	Description
200	OK
204	No content / Object deleted
400	Bad Request / Returns JSON with the error message
401	Unauthorized / Couldn't authenticate your request
404	Not found / No such object
500	Internal Server Error
503	Service Unavailable / The connection is being throttled or the service is down for maintenance

Response Cases

Case 1: If the received response is null, then we keep the corresponding webhook invocation as FAILED to be retried after a certain period (depending on the webhook retry configuration of each environment) and we set the error in Paylican Invoice to SYNCH_UNAVAILABLE.

Case 2: If the HTTP response is returned with 2xx code then we mark the corresponding webhook invocation as SUCCESSFULL and we set its status to INVOCATION_SUCCESS. In case a content gets sent in the response body it gets saved in the Paylican Invoice database.

Case 3: If the HTTP response code IS NOT 2xx then we mark the corresponding webhook invocation as FAILED to be retried after a certain period (depending on the webhook retry configuration of each environment) and we set its status to INVOCATION_FAIL. In case a content gets sent in the response body it gets saved in the Paylican Invoice database.