menu

Payment API

What's on this page

API Reference / Refund

Refund

Refunds are allowed for all existing payment methods, except LandingPage, Token and Vault.

  • Full refunds and partial refunds are supported
  • For some payment methods, refunds above the original amount may be accepted
  • For some payment methods, we apply balance calculations per day. This allows you to refund as much as you earned that day. If your balance is insufficient, the transaction is denied with failure code UNSUFFICIENT_BALANCE

Refund object

Name Description
type Fixed value: refund
amount The refund amount
currency Echo from the Payment
status Possible values: Transaction Status
paidout A boolean value that indicates if this transaction has been paid out. Only available for collecting protocols. Possible values: yes or no
paidoutDate The date when the payment to the customer was done. Only valid for collecting protocols.
merchantOrderReference Echo from the Payment
description A description of the transaction
language Echo from the Payment
method Echo from the Payment
brand Echo from the Payment
metadata Echo from the Payment
reference A unique reference for the refund transaction
originalReference The unique reference for the payment transaction this payment is attempting to refund.
unstructuredReference The unstructured reference used when performing the payout to the merchant. Only valid for collecting protocols
paidoutReference The reference used when performing the payout to the customer. This can be used to look up transactions related to that payout. Only valid for collecting protocols
created The local server datetime the refund was created, epoch timestamp
lastUpdate The local server datetime the refund was updated, epoch timestamp
statusFinalDate The local server datetime the refund reached a final status, epoch timestamp
failureCode An error code indication what caused the failure. Possible values: Failure Codes
payUrl To complete the payment the customer should be redirected to this unique URL. Only valid for Terminal
returnUrl After the payment is completed (successfully or otherwise) the customer is redirected to this URL. Only valid for Terminal
payoutInstructions Optional list of Payout Instruction set by the refund initiator to indicate which merchants of the original payment were eligible for a refund. See Split Payout for more info.

Payout instruction refund object

A payout instruction can be used to provide a custom structured reference and facilitate Split Payouts. Multiple Payout Instructions can only be used when boarded for Split Payout.

Name Description
externalReference This is the reference to the sub merchant for this payout instruction.
amount The amount to withhold for pay out to the sub merchant.
paidout A boolean value that indicates that the payout instruction’s amount is withheld from a pay out to the sub merchant. Possible values: yes or no
paidoutDate An epoch timestamp of the payout to the sub merchant where this payout instruction is withheld from.
unstructuredReference The message used in the payout to the sub merchant.
paidoutReference The reference to the payout to the sub merchant.

Example

{
  "externalReference" : "0001606469162213",
  "amount" : 5.00,
  "paidout" : "yes",
  "paidoutDate": 1605258439475,
  "unstructuredReference": "579fd569 AFREK. CCV PAY DAT. 20201113/0318 AANT. 3 MREF. Lamp Shop",
  "paidoutReference": "579fd569"
}

Refund request

  • Resource: /api/v1/refund
  • Method: POST
  • Content-Type: application/json
  • Authentication: basic auth
  • Supports idempotency
  • Parameters
Name Required Description Max Length
reference Yes The unique reference of the payment to refund 255
description No The description of the refund. If not provided we use the original payment description 255
amount No The amount to refund. If not provided we use the original payment amount. The currency used will be the currency of the original payment and the format must be the same 12 digits in total, of which maximum 2 decimal digits
webhookUrl No The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url 2000
returnUrl No The customer is redirected to this URL after the payment is completed (successfully or otherwise). If provided it must include a scheme to be usable for browser redirection or Android/iOs app usage. We do not validate the provided URL. Only valid for Terminal. 2000
notificationRequests No An object which is used to request Notifications for specific events related to this refund. n/a
payoutInstructions No Optional list of Payout Instruction to indicate which merchants of the original payment were eligible for a refund. See Split Payout for more info. n/a
details No An object which includes method specific details. Possible values: Method Refund Details. n/a

Example

{
  "reference": "C1505181754007360.1",
  "description": "API Refund Description"
}

Method Refund Details

Terminal Refund Details

These details are required when refunding a payment which was made using the method terminal.

Name Required Description Max Length
terminalId Yes The terminal id as assigned by CCV 50
managementSystemId Yes The management system id of this terminal as assigned by CCV 50
accessProtocol Yes The communication protocol between the terminal and access server 20
operatingEnvironment No The environment in which the terminal is operating. Possible values: ATTENDED and SEMI_UNATTENDED. Defaults to SEMI_UNATTENDED when empty. 20
merchantLanguage Yes/No The language of the merchant, used to change the language in which the intermediate page is displayed in ATTENDED operatingEnvironments. Required when operatingEnvironment is ATTENDED, not required otherwise. 3

Example

{
  "reference": "T1505181754007760.Y",
  "description": "API Refund Description for Terminal Transaction",
  "details" : {
    "managementSystemId" : "000103030",
    "terminalId" : "1234536",
    "accessProtocol" : "OPI_NL",
    "operatingEnvironment" : "ATTENDED",
    "merchantLanguage" : "NLD"
  }
}

Payout Instruction Refund Request Details

A payout instruction can be used to provide a custom structured reference and facilitate Split Payouts. Multiple Payout Instructions can only be used when boarded for Split Payout.

Requirements:

  • Payout instructions are required when the original payment contains payout instructions
  • The sum of all payout instructions must match the refund amount
  • The refund amount for each payout instruction is required
  • Partial refunds on payout instructions are allowed
Name Description
externalReference This is the reference to the merchant for this payout instruction. Present when the payment requires multiple payout instructions to identify different merchants.
amount The amount to be withheld for pay out to the referenced merchant.

Example

{
  "externalReference" : "0001606469162213",
  "amount" : 5.00
}

Refund response

  • Status Code: 200
  • Content Type: application/json
  • Content: Refund

Example

{
  "type" : "refund",
  "amount" : 316.35,
  "currency" : "eur",
  "status" : "PENDING",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Refund Description",
  "language" : "eng",
  "method" : "card",
  "metadata" : "my custom metadata",
  "reference" : "C1505181613078800.1",
  "brand" : "visa",
  "created" : 1431958387914,
  "lastUpdate" : 1431958387914,
  "statusFinalDate" : 1431958387914
}