Invoice Refund Request

Only available for payment method: Invoice

A refund request for invoice can be sent from the merchant when the customer don't need to pay anymore for a line. For example when the line is Canceled or Returned . The merchant can send a refund request for one or more lines of a payment request.

We expect from the merchant an endpoint to send the result of the invoice refund request. When the invoice refund request is Accepted, then Tinka will cancel or refund the invoice for the customer.

URL

POST /merchant-api/v2/invoices/{paymentRequestId}/refunds

HTTP response codes

200 - Successful operation
400 - Request body not as expected. MerchantLineReference does not exist for the given payment request. NumberOfItems can't be refunded. Payment method not allowed. MerchantRefundReferenceId already exists.
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
404 - Payment request for given ID does not exist

Request

Attribute	Type	Length	Description
`merchantRefundReferenceId` required	String	100	A reference provided by the merchant. Must be unique.
`lines` required	List of Line
`callbackUrl` required	String	2048	The URL on which the result of the invoice refund request can be send.

Line

Attribute	Type	Length	Description
`merchantLineReference` required	String	100	The reference to the original line in the payment request. Must be unique per invoice refund request
`numberOfItems` required	Integer		The number of items to be refunded

Response

Attribute	Type	Length	Description
`refundId` required	String	36	Unique identifier issued by Tinka. It is a UUID.

Example

Request

{
    merchantRefundReferenceId: 'merchant-refund-id-1',
    lines: [{
      merchantLineReference: 'Example_0000001',
      numberOfItems: 1
    }],
    callbackUrl: 'https://merchant.nl/refund'
}

Response

{
  refundId: '65446767-ffff-tttt-5555-34567321abc';
}

Callback Invoice Refund Request

The merchant needs to have an endpoint available where Tinka can send an update of the invoice refund request. The message below is sent to this endpoint in JSON format with a HTTP POST request. The request will be signed in the same way a response of a synchronous call is signed. The signature will be sent via a HTTP header: X-Authorization: hmac <merchant-id>:<hash>:<nonce>:<timestamp> for more information see security.

Request Body for endpoint

Attribute	Type	Length	Description
`refundId` required	String	36	A unique number for this invoice refund request transaction. It`s a UUID
`paymentRequestId` required	String	36	A unique number for this payment request transaction. It`s a UUID
`decision` required	Enum String		The decision of the InvoiceRefundRequest. Possible values `Accepted`, `Rejected`
`rejectionReason`	String	255	The possible reason for the rejection of the refund request

Example

Accepted Request Body for endpoint

{
  refundId: '65446767-ffff-tttt-5555-34567321abc',
  paymentRequestId: '01234567-aaaa-bbbb-cccc-987654321abc',
  decision: 'Accepted'
}

Rejected Request Body for endpoint

{
  refundId: '65446767-ffff-tttt-5555-34567321abc',
  paymentRequestId: '01234567-aaaa-bbbb-cccc-987654321abc',
  decision: 'Rejected',
  rejectionReason: 'All lines where already refunded'
}