Tinka Developer Portal

Tinka

Introduction

Payment process online

In general there are two phases in the payment process:

  1. Request to pay with a specific payment method (the payment request) We capture directly after the acceptance of the contract/payment

  2. Modification of a request consisting of:

    1. Cancellation
    2. Refund

Payment process offline

In general there are two phases in the payment process:

  1. Request to pay with barcode and a specific payment method (the payment request). We do a direct capture.
  2. Modification of a request consisting of:
    1. Refund

Payment methods

Possible values for payment method:

Payment methodDescription
CreditPay in monthly installments, current interest rate applies to the total credit balance.
ZeroPercentCreditPay in 12 monthly installments, customer does not pay interest on this specific amount.

Payment request decision

Possible values for a decision of a payment request:

DecisionEnd stateDescription
InProgressNoPayment request is received, processing has not been completed.
AcceptedYesThe requested payment method is accepted.
RejectedYesThe requested payment method is rejected.
CancelledYesThe request is cancelled by the customer or merchant.
PendingNoSome additional steps need to be performed in order to accept or reject. This decision is not implemented yet.

Security

Authorization is being done on three levels

  1. IP whitelisting
  2. Basic authentication
  3. Request signing using HMAC

HMAC

Requests to Lacent

All requests to Lacent need to have the correct HTTP header for signing:

X-Authorization: hmac <merchant-id>:<hash>:<nonce>:<timestamp>

  • hmac: Authentication scheme, is always hmac
  • merchant-id: id provided by Lacent to identify the merchant. This is used to lookup the secret key used to sign the request
  • hash: base64 encoded HMAC SHA256 hash. The content for the hash is a concatenated string consisting of merchant-id, timestamp, nonce and request content separated by semicolons. The HMAC is signed with the secret key.
  • nonce: random sequence of characters that should be different for each request, valid characters: a-z, A-Z, 0-9, ‘-‘
  • timestamp: request time in seconds since the epoch (01-01-1970 00:00:00) in UTC time

The hash is calculated over a concatenated string consisting of merchant-id, timestamp, nonce and request content separated by semicolons.

The request content can either be

  • the URL path and the JSON body in case of a POST or PUT separated by a semicolon
  • the URL path followed by a semicolon in case of a GET request. Some examples:
  • POST to /merchant-api/v2/online/payment-requests with body { “key1”: “value1” } : the input for the hash is “/merchant-api/online/v2/payment-requests;{ “key1”: “value1” }”
  • POST to /merchant-api/v2/refunds/12345678 with body { “key1”: “value1” } : the input for the hash is “/merchant-api/v2/refunds/12345678;{ “key1”: “value1” }”
  • GET /merchant-api/v2/status/12345678: the input for the hash is “/merchant-api/v2/status/12345678;”

Response from Lacent

Responses from Lacent are also signed. For this purpose the HTTP header X-Authorization is used. This header will have the following structure:

X-Authorization: hmac <merchant-id>:<hash>:<nonce>:<timestamp>

  • hmac: Authentication scheme, is always hmac
  • hash: base64 encoded HMAC SHA256 hash. The content for the hash is a concatenated string consisting of merchant-id, timestamp, nonce and request content separated by semicolons. The HMAC is signed with the secret key.
  • nonce: random sequence of characters that should be different for each request, valid characters: a-z, A-Z, 0-9, ‘-‘
  • timestamp: request time in seconds since the epoch (01-01-1970 00:00:00) in UTC time

The hash is calculated over a concatenated string consisting of merchant-id, timestamp, nonce and response content (or the empty string if there is no body) separated by semicolons.