Online Payment Request
API description with the corresponding required attributes for all payment requests.
URL
POST
/merchant-api/v2/online/payment-requests
HTTP response codes
200
- Successful operation401
- Unauthorized, maybe the credentials are missing. For more information, see security403
- Forbidden, the HMAC may be wrong or out of date. For more information, see security
Request
Attribute | Pay in 14 days (Invoice) | Credit | Type | Length | Description |
---|---|---|---|---|---|
transactionId | required | required | String | 100 | A reference provided by the caller. We recommend to use this for linking the payment request and make it unique for every transaction. |
merchantRequestReference | required | required | String | 100 | A reference provided by the merchant. We recommend to use this for linking the payment request. |
paymentMethod | required | required | Enum String | See Payment methods . | |
requestedPaymentAmount | required | required | Integer | The amount that is needed by the customer to pay the purchase. The requested amount is always in euro cents and should be > 0 and <= the combined orderline values. | |
invoiceAddress | required | *recommended | Address | ||
delivery | required | *recommended | DeliveryCharacteristics | ||
payments | - | - | List of Payment | ||
requestTags | required | - | List of RequestTag | ||
merchant | required | required | Merchant | ||
lines | required | required | List of Line | ||
applicant | required | required | Applicant | ||
routing | - | required | Routing | This field is required and available only for Credit payment method. | |
session | required | - | Session | This field is required and available only for Invoice payment method. | |
orderCreationDate | required | - | String | 24 | This field is required and available only for Invoice payment method. The date and time when the order is created. Date time is in UTC Format: yyyy-MM-ddTHH:mm:ss.SSSZ |
*We strongly recommend to complete this field if it is available, as it has an impact on conversion rate.
Responses
Response of the Credit
payment request call
Attribute | Type | Length | Description |
---|---|---|---|
paymentRequestId required | String | 36 | A unique number for this payment request transaction. It is a UUID. |
redirectUrl required | String | 2000 | The URL the customer has to go to in order to finish the payment. The merchant needs to redirect the customer to this URL. |
Response of the Invoice
payment request
We support two flavours. A-synchronize call and synchronize call.
Synchronize
With a synchronize call you will get the paymentRequestId and the decision returned. This option will take a bit longer. The merchant also get the decision via the a-synchronize callback.
Attribute | Type | Length | Description |
---|---|---|---|
paymentRequestId required | String | 36 | A unique number for this payment request transaction. It is a UUID. |
decision required | Enum String | The decision of the paymentRequest. Possible options Accepted , Rejected , Cancelled . See decision |
A-synchronize
With an a-synchronize call you will get a paymentRequestId returned. The merchant then needs to wait on the a-synchronize callback, described at here. Or can ask for the current status via this endpoint
Attribute | Type | Length | Description |
---|---|---|---|
paymentRequestId required | String | 36 | A unique number for this payment request transaction. It is a UUID. |
Type: Address
Attribute | Pay in 14 days (Invoice) | Credit | Type | Length | Description |
---|---|---|---|---|---|
countryCode | required | required | Enum String | 10 | The country code of the address. For now this should always be NL |
houseNumber | required | required | String | 10 | The house number of the given address. |
houseNumberAddition | - | - | String | 10 | The addition to the house number. |
postalCode | required | required | String | 10 | The (official) postcode of the address. The postal code requires the format NNNNAA or NNNN AA for Dutch postal codes. Example: 8011NW |
street | required | required | String | 50 | The name of the street. |
city | required | required | String | 50 | The name of the city. |
Type: Applicant
Attribute | Pay in 14 days (Invoice) | Credit | Type | Length | Description |
---|---|---|---|---|---|
dateOfBirth | required | - | String | 10 | The date of birth of the customer. Format: yyyy-mm-dd |
emailAddress | required | - | String | 320 | The email address of the customer. We don`t validate if an email address is valid or not. |
externalCustomerNumber | - | - | String | 100 | Number provided by the the merchant to identify the customer uniquely. The customer number (or customer reference) of the merchant |
gender | required | - | Enum String | 10 | Gender is (in the context of credit payment) important because gender determines how we perform a BKR check. Possible values: Male ,Female , Unknown |
initials | required | - | String | 20 | The initials of the customer. Valid formats for the initials: S.T. , ST , S T , S. , S ,Ö . Regex model: ^[\\p{IsLatin}][\\p{IsLatin}. ]*$ |
firstName | - | - | String | 100 | First name of the customer. |
prefixLastName | - | - | String | 10 | The prefix of the last name. Examples : “van” or “van der” |
lastName | required | required | String | 200 | The last name of the customer. As for credit we have an obligation to register a new loan on birth name. The general rule at Tinka is to ask for a birth name when gender is female. For this specific situation Tinka will ask for a birth name during the acceptance process (if needed of course) |
telephoneNumber | required | - | String | 17 | The phone number the customer has provided. Phone can either be a landline or a mobile number |
Type: Delivery characteristics
Attribute | Pay in 14 days (Invoice) | Credit | Type | Length | Description |
---|---|---|---|---|---|
deliveryDate | - | - | String | 10 | The date the delivery of the goods will take place. Format: yyyy-mm-dd |
deliveryMethod | required | - | Enum String | The way the goods are delivered. This is important because it will have an effect on fraud detection. I.e. when a customer wants to pick up the goods in a store it will probably be a safer method than delivering the goods to a delivery parcel station. Possible values: CompanyDelivery ,Locker , ParcelStation , ParcelShop ,CompanyStore , ShippingPartner | |
deliveryAddress | required | - | Address | The address where the goods will be delivered. | |
notificationEmailAddress | - | - | String | 320 | Email address where the customer wants the notification. |
notificationTelephoneNumber | - | - | String | 18 | Phone number where the customer wants the notification. Phone can either be a landline or a mobile number |
shippingPartner | - | - | String | 100 | The company who is going to deliver the products. DHL/PostNL/etc… |
Type: Line
Attribute | Pay in 14 days (Invoice) | Credit | Type | Length | Description |
---|---|---|---|---|---|
itemPrice | required | required | Integer | The price of an individual line item. Amounts are always in Euro cents and include VAT. | |
merchantLineReference | required | required | String | 100 | Unique reference of the merchant of the line item. |
productClassification | required | - | String | 100 | Description of classification of the product. |
numberOfItems | required | required | Integer | The number of items on the line. Must be more than 0 . | |
description | required | required | String | 255 | The description of a line item. |
brand | - | - | String | 100 | The brand of the product. |
manufacturer | - | - | String | 100 | The manufacturer of the product. |
color | - | - | String | 100 | Color of the product. |
size | - | - | String | 100 | Size of the product. |
The sum of order lines must be same as the requested payment amount. Prepayments processed by Tinka will be deducted first from the requested payment amount. Also, merchantLineReference must be unique across the order lines in the same payment request (this is needed for capture and refund process).
Type: Payment
Is a list of already carried out payments for this request (e.g. via gift card).
Attribute | Pay in 14 days (Invoice) | Credit | Type | Length | Description |
---|---|---|---|---|---|
amount | required | required | Integer | The amount of the payment as recorded by the merchant. It is always in euro cents and has to be a positive number (amount > 0) | |
paymentType | required | required | String | 100 | Free format payment type as reference for the merchant. |
Type: Request tag
One or more key value pairs provided by the merchant.
For Invoice
tag with tagName PromotionCodeApplied
is required Possible tagValues are true
of false
You can add more tags, for example a key “campaign” and a value “christmas 2018” or key “store” with value “Zwolle”.
Attribute | Pay in 14 days (Invoice) | Credit | Type | Length | Description |
---|---|---|---|---|---|
tagName | required | required | String | 50 | The name of the tag |
tagValue | required | required | String | 100 | The value of the tag |
Type: Merchant
Unique identification of the merchant provided by Tinka. This field is required for all payment methods.
Attribute | Type | Length | Description |
---|---|---|---|
merchantId required | String | 100 | The unique id of the merchant provided by Tinka. Should be the same as the merchant id used to sign the request |
Type: Routing
URLs for routing the customer back to the merchant's website. This field is available and required only for Credit
.
Attribute | Type | Length | Description |
---|---|---|---|
callbackUrl | String | 2000 | URL to send the customer to after the payment flow has been completed. For all outcomes (Accepted, Rejected, Pending) except Cancelled |
cancelUrl | String | 2000 | URL for landing page when customers explicitely cancel the flow. |
The following query parameters will be appended to each of the above URLs: merchantRequestReference
, requestedPaymentAmount
, paymentMethod
, decision
, decisionDateTime
, nonce
, paymentRequestId
, timestamp
, transactionId
, shaSign
.
The shaSign
is the HMAC hash of the previous parameters.
Type: Session
Information about the current session of the customer. This field is available and required only for Invoice
.
Attribute | Type | Length | Description |
---|---|---|---|
ipAddress | String | 50 | Ip address of the session in checkout of the merchant. |
userAgent | String | 512 | The HTTP “User-Agent” header of the browser used in the transaction |
acceptLanguage | String | 256 | The HTTP “Accept-Language” header of the device used in the transaction. |
sessionAge | Integer | The number of seconds between the creation of the user’s session and the time of the transaction. Note that session_age is not the duration of the current visit, but the time since the start of the first visit. The value must be greater than 0 . | |
sessionId | String | 100 | An ID that uniquely identifies a visitor’s session on the site. |
Example
Credit request
fetch('https://....../merchant-api/v2/online/payment-requests', {
method: 'POST',
headers: {
Authorization: 'Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-Authorization': 'hmac example:xxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxx/xxx=:nonce:xxxxxxxxxx',
'Content-Type': 'application/json'
},
body: {
transactionId: 'unique-xxxxxxxxxxxxxxxxxxxx',
merchantRequestReference: 'xxxxxxxxxxxxxxxx',
paymentMethod: 'Credit', // for credit payment
requestedPaymentAmount: 90000, // === 900 Euro
invoiceAddress: {
countryCode: 'NL',
houseNumber: '81',
houseNumberAddition: null,
postalCode: '4006EA'
street: 'Dodewaardlaan',
city: 'Tiel',
},
delivery: {
deliveryDate: '2020-02-02',
deliveryAddress: {
countryCode: 'NL',
houseNumber: '81',
houseNumberAddition: null,
postalCode: '4006EA'
street: 'Dodewaardlaan',
city: 'Tiel',
},
deliveryMethod: 'CompanyDelivery'
},
routing: {
callbackUrl: 'https://www.example.com/callback',
cancelUrl: 'https://www.example.com/cancel'
},
payments: [
{
amount: 1500, // === 15 Euro
paymentType: 'some special gift card'
}
],
requestTags: [
{
tagName: 'campaign',
tagValue: 'christmas event 2018'
}
],
merchant: {
merchantId: 'example'
},
lines: [
{
itemPrice: 44250,
merchantLineReference: 'Example_xxxxxxxxx',
productClassification: '1001',
numberOfItems: 2,
description: 'some description xxxxxxxxxx'
}
],
applicant: {
dateOfBirth: '1971-01-01',
emailAddress: '[email protected]',
externalCustomerNumber: 'xxxxxxxxxxxxxx',
gender: 'Male',
initials: 'S.',
firstName: 'Nosmyut',
prefixLastName: null,
lastName: 'Proefpersoonlangnaamdeel'
telephoneNumber: '0131234567',
}
}
})
Credit response
const example_response = {
paymentRequestId: '01234567-aaaa-bbbb-cccc-987654321abc',
redirectUrl: 'https://www.tinka.com/gespreidbetalen?paymentRequestId=01234567-aaaa-bbbb-cccc-987654321abc'
};
// redirect the customer to our website
window.location = example_response.redirectUrl;
Invoice request
fetch('https://....../merchant-api/v2/online/payment-requests', {
method: 'POST',
headers: {
Authorization: 'Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-Authorization': 'hmac example:xxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxx/xxx=:nonce:xxxxxxxxxx',
'Content-Type': 'application/json'
},
body: {
transactionId: 'unique-xxxxxxxxxxxxxxxxxxxx',
merchantRequestReference: 'xxxxxxxxxxxxxxxx',
paymentMethod: 'Invoice',
requestedPaymentAmount: 90000, // === 900 Euro
orderCreationDate: '2021-03-04T18:44:55.000Z',
invoiceAddress: {
countryCode: 'NL',
houseNumber: 81,
houseNumberAddition: null,
postalCode: '4006EA'
street: 'Dodewaardlaan',
city: 'Tiel',
},
delivery: {
deliveryDate: '2020-02-02',
deliveryAddress: {
countryCode: 'NL',
houseNumber: 81,
houseNumberAddition: null,
postalCode: '4006EA'
street: 'Dodewaardlaan',
city: 'Tiel',
},
deliveryMethod: 'CompanyDelivery'
},
session: {
ipAddress: '127.0.0.1',
userAgent: 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
acceptLanguage: 'en-US,en;q=0.9,nl;q=0.8',
sessionAge: 1,
sessionId: 'id1'
},
payments: [
{
amount: 1500, // === 15 Euro
paymentType: 'some special gift card'
}
],
requestTags: [
{
tagName: 'PromotionCodeApplied',
tagValue: 'true'
}
],
merchant: {
merchantId: 'example'
},
lines: [
{
itemPrice: 20000, // === 200 euro
merchantLineReference: 'Example_xxxxxxxxx',
productClassification: 'Fashion',
numberOfItems: 2,
description: 'some description xxxxxxxxxx'
},{
itemPrice: 50000, // === 500 euro
merchantLineReference: 'Example_xxxxxxxxx',
productClassification: 'Furniture',
numberOfItems: 1,
description: 'some description xxxxxxxxxx'
}
],
applicant: {
dateOfBirth: '1971-01-01',
emailAddress: '[email protected]',
externalCustomerNumber: 'xxxxxxxxxxxxxx',
gender: 'Male',
initials: 'S.',
firstName: 'Nosmyut',
prefixLastName: null,
lastName: 'Proefpersoonlangnaamdeel'
telephoneNumber: '0131234567'
}
}
})
Invoice response a-synchronize call
const example_response = {
paymentRequestId: '01234567-aaaa-bbbb-cccc-987654321abc'
};
Invoice response synchronize call
const example_response = {
paymentRequestId: '01234567-aaaa-bbbb-cccc-987654321abc'
decision: 'Accepted'
};