Introduction

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

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

In general there are two phases in the payment process:

1. Receive a Request to pay with Invoice

   1. Directly return an Accepted or Rejected. When something went wrong we will cancel the payment request after a few hours
   2. Payment request is waiting for a Capture of Refund.

2. Modification of a request consisting of:

   1. Capture
   2. Cancellation
   3. Refund

Possible values for payment method:

Possible values for a decision of a payment request:

Authorization is being done on three levels

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

Requests to Tinka

All requests to Tinka 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 Tinka 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 Tinka

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

X-Authorization: hmac <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.