Tinka

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 operation
  • 401 - Unauthorized, maybe the credentials are missing. For more information, see security
  • 403 - Forbidden, the HMAC may be wrong or out of date. For more information, see security

Request

AttributePay in 14 days (Invoice)CreditTypeLengthDescription
transactionIdrequiredrequiredString100A reference provided by the caller.
We recommend to use this for linking the payment request and make it unique for every transaction.
merchantRequestReferencerequiredrequiredString100A reference provided by the merchant.
We recommend to use this for linking the payment request.
paymentMethodrequiredrequiredEnum StringSee Payment methods .
requestedPaymentAmountrequiredrequiredIntegerThe 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.
invoiceAddressrequired*recommendedAddress
deliveryrequired*recommendedDeliveryCharacteristics
payments--List of Payment
requestTagsrequired-List of RequestTag
merchantrequiredrequiredMerchant
linesrequiredrequiredList of Line
applicantrequiredrequiredApplicant
routing-requiredRoutingThis field is required and available only for Credit payment method.
sessionrequired-SessionThis field is required and available only for Invoice payment method.
orderCreationDaterequired-String24This 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

AttributeTypeLengthDescription
paymentRequestId requiredString36A unique number for this payment request transaction. It is a UUID.
redirectUrl requiredString2000The 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.

AttributeTypeLengthDescription
paymentRequestId requiredString36A unique number for this payment request transaction. It is a UUID.
decision requiredEnum StringThe 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

AttributeTypeLengthDescription
paymentRequestId requiredString36A unique number for this payment request transaction. It is a UUID.


Type: Address

AttributePay in 14 days (Invoice)CreditTypeLengthDescription
countryCoderequiredrequiredEnum String10The country code of the address.
For now this should always be NL
houseNumberrequiredrequiredString10The house number of the given address.
houseNumberAddition--String10The addition to the house number.
postalCoderequiredrequiredString10The (official) postcode of the address.
The postal code requires the format NNNNAA or NNNN AA for Dutch postal codes.
Example: 8011NW
streetrequiredrequiredString50The name of the street.
cityrequiredrequiredString50The name of the city.

Type: Applicant

AttributePay in 14 days (Invoice)CreditTypeLengthDescription
dateOfBirthrequired-String10The date of birth of the customer.
Format: yyyy-mm-dd
emailAddressrequired-String320The email address of the customer.
We don`t validate if an email address is valid or not.
externalCustomerNumber--String100Number provided by the the merchant to identify the customer uniquely.
The customer number (or customer reference) of the merchant
genderrequired-Enum String10Gender is (in the context of credit payment) important because gender determines how we perform a BKR check.
Possible values: Male,Female, Unknown
initialsrequired-String20The initials of the customer.
Valid formats for the initials: S.T., ST, S T, S., S,Ö. Regex model: ^[\\p{IsLatin}][\\p{IsLatin}. ]*$
firstName--String100First name of the customer.
prefixLastName--String10The prefix of the last name.
Examples : “van” or “van der”
lastNamerequiredrequiredString200The 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)
telephoneNumberrequired-String17The phone number the customer has provided.
Phone can either be a landline or a mobile number

Type: Delivery characteristics

AttributePay in 14 days (Invoice)CreditTypeLengthDescription
deliveryDate--String10The date the delivery of the goods will take place.
Format: yyyy-mm-dd
deliveryMethodrequired-Enum StringThe 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
deliveryAddressrequired-AddressThe address where the goods will be delivered.
notificationEmailAddress--String320Email address where the customer wants the notification.
notificationTelephoneNumber--String18Phone number where the customer wants the notification.
Phone can either be a landline or a mobile number
shippingPartner--String100The company who is going to deliver the products.
DHL/PostNL/etc…

Type: Line

AttributePay in 14 days (Invoice)CreditTypeLengthDescription
itemPricerequiredrequiredIntegerThe price of an individual line item.
Amounts are always in Euro cents and include VAT.
merchantLineReferencerequiredrequiredString100Unique reference of the merchant of the line item.
productClassificationrequired-String100Description of classification of the product.
numberOfItemsrequiredrequiredIntegerThe number of items on the line.
Must be more than 0.
descriptionrequiredrequiredString255The description of a line item.
brand--String100The brand of the product.
manufacturer--String100The manufacturer of the product.
color--String100Color of the product.
size--String100Size 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).

AttributePay in 14 days (Invoice)CreditTypeLengthDescription
amountrequiredrequiredIntegerThe amount of the payment as recorded by the merchant.
It is always in euro cents and has to be a positive number (amount > 0)
paymentTyperequiredrequiredString100Free 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”.

AttributePay in 14 days (Invoice)CreditTypeLengthDescription
tagNamerequiredrequiredString50The name of the tag
tagValuerequiredrequiredString100The value of the tag

Type: Merchant

Unique identification of the merchant provided by Tinka. This field is required for all payment methods.

AttributeTypeLengthDescription
merchantId requiredString100The 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.

AttributeTypeLengthDescription
callbackUrlString2000URL to send the customer to after the payment flow has been completed. For all outcomes (Accepted, Rejected, Pending) except Cancelled
cancelUrlString2000URL 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.

AttributeTypeLengthDescription
ipAddressString50Ip address of the session in checkout of the merchant.
userAgentString512The HTTP “User-Agent” header of the browser used in the transaction
acceptLanguageString256The HTTP “Accept-Language” header of the device used in the transaction.
sessionAgeIntegerThe 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.
sessionIdString100An 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'
};

© 2024 Tinka. All Rights Reserved. All trademarks, service marks and trade names used in this material are the property of their respective owners.