Offline Payment Request

URL

POST /merchant-api/v2/offline/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

Attribute	Type	Length	Description
`transactionId` 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	String	100	A reference provided by the merchant. We recommend to use this for linking the payment request
`paymentMethod` required	Enum String		See Payment methods .
`requestedPaymentAmount` 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`	Address
`delivery`	DeliveryCharacteristics
`routing`	Routing
`payments`	List Of Payment
`requestTags`	list of RequestTag
`merchant` required	Merchant
`lines`	List of Line
`applicant`	Applicant
`customerBarcodeToken` required	String	128	A unique set of characters that identifies the Tinka customer

Response

Response of the offline payment request call

Attribute	Type	Length	Description
`paymentRequestId` required	String	36	A unique number for this payment request transaction. It`s a UUID
`paymentMethod` required	String	2000	The original payment method. Can be used for extra verification on the merchant's side
`requestedPaymentAmount` required	Integer		The original requested amount in euro cents. Can be used for extra verification on the merchant's side
`decision` required	Enum String		The decision of the paymentRequest. Can be `Accepted`, `Rejected`. See decision.
`decisionDateTime` required	String		Date of the decision. Format `yyyy-mm-ddThh:mi:ss.SSSZ` In UTC timezone. Example: `2018-11-06T09:41:25.020Z`
`transactionId` required	String	100	A reference provided by the caller. Can be used for extra verification on the merchant's side
`merchantRequestReference` required	String	100	A unique reference provided by the merchant. Can be used for extra verification on the merchant's side
`errorCode`	String		Error code (indication of the nature of the error). List of error codes needs to be decided
`additionalData`	String	255	Additional info for the payment request. Possibly a reject reason or error message

Type: Address

Attribute	Type	Length	Description
`countryCode` required	Enum String	10	For now this will always be `NL`
`houseNumber` required	String	10
`houseNumberAddition`	String	10
`postalCode` required	String	10	The postal code has the format of `NNNNAA` or`NNNN AA` for Dutch postal codes(i.e. 8011NW)
`street` required	String	50
`city` required	String	50

Type: Applicant

Attribute	Type	Length	Description
`dateOfBirth`	String	10	The date of birth of the customer. Format: `yyyy-mm-dd`
`emailAddress`	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`	String	20	The initials of the customer.
`firstName`	String	100	First name of the customer.
`prefixLastName`	String	10	The prefix of the last name. Examples : “van” or “van der”
`lastName` 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`	String	17	The phone number the customer has provided. Phone can either be a landline or a mobile number

Type: Delivery characteristics

Attribute	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	Type	Length	Description
`itemPrice` required	Integer		The price of an individual line item. Amounts are always in euro cents and include VAT.
`merchantLineReference` required	String	100	Unique reference of the merchant of the line item.
`productClassification`	String	100	Description of classification of the product.
`numberOfItems` required	Integer		The number of items on the line. should be greater than `0`.
`description` 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.

Type: Payment

Is a list of already carried out payments for this request (e.g. via gift card).

Attribute	Type	Length	Description
`amount` required	Integer		The amount of the payment as recorded by the merchant. Amount is always in euro cents and has to be a positive number (amount > 0)
`paymentType` 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 example a key “campaign” and a value “christmas 2018” or key “store” with value “Zwolle”.

Attribute	Type	Length	Description
`tagName` required	String	50	The name of the tag
`tagValue` required	String	100	The value of the tag

Type: Merchant

Unique identification of the merchant provided by Tinka.

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.

Attribute	Type	Length	Description
`callbackUrl` required	String	2000	URL to send the customer to after the payment flow has been completed. For all outcomes (`Accepted`, `Rejected`, `Pending`) except `Cancelled`
`cancelUrl` required	String	2000	URL for landing page when customers explicitely cancel the flow

Example

Request

fetch('https://....../merchant-api/v2/offline/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: 10000, // === 100 Euro
        paymentType: 'some special gift card'
      }
    ],
    requestTags: [
      {
        tagName: 'campaign',
        tagValue: 'christmas event 2018'
      }
    ],
    merchant: {
      merchantId: 'example'
    },
    lines: [
      {
        itemPrice: 50000,
        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',
    },
    customerBarcodeToken: "xxxxxxxxxx"
  }
})

Response

const example_response = {
  paymentRequestId: '01234567-aaaa-bbbb-cccc-987654321abc',
  paymentMethod: 'Credit',
  requestedPaymentAmount: 90000,
  decision: 'Accepted',
  decisionDateTime: '2020-02-02T09:40:00.020Z',
  transactionId: 'unique-xxxxxxxxxxxxxxxxxxxx',
  merchantRequestReference: 'xxxxxxxxxxxxxxxx'
};