Refund API

With the REST API for Refunds, you can refund a transaction to the consumer automatically.

The Refund process in short:

  1. Create a refund for an existing, successful transaction. (Create Method)
  2. Every night, DigiWallet checks your Virtual Bank Account balance to pay for the refund. If you have enough outstanding credit, the refund will be confirmed. If not, you will be mailed a notification. When short on credit, you can always manually top your credit off through the DigiWallet Backoffice.
  3. Confirmed refunds are paid out to consumers multiple times a week.
  4. A newly created refund can be removed as long as it has not been confirmed yet. (Delete Method)

HTTP Bearer Authentication

This API requires HTTP Bearer authentication (Read more...) This means your requests to this API must always be accompanied by an HTTP header carrying your organization's API key to be accepted.

You can find your organization's unique API token in your Organization Dashboard.

An example of the HTTP header is as follows: 

Authorization: Bearer 12a34bc5de67f8g9012345678

RESTful API

This is a RESTful API. This means the API follows the RESTful format for web services (Read more...)

The response format for these API's is in (JSON). A typical response will be a JSON-encoded array with a status integer to indicate whether the call was successful or not, and a message string with a description of what happened.

Beyond these standard elements, an API can return API-specific information. e.g. transactionID integer for the creation of a transaction. Or a nested errors array providing detailed validation errors.

The HTTP response codes of the RESTful API's follow the below logic:

HTTP Status Code Used in response to
200 (Success) A successfully processed request that also returns information
201 (Created) A successfully processed creation request
202 (Accepted) A successfully accepted job request
400 (Bad Request) Bad input parameters / validation errors
401 (Unauthorized) Bad credentials
404 (Not Found) Resource could not be found
405 (Method Not Allowed) Method is unsupported in the API
500 (Internal Server Error) A problem occurred at DigiWallet's servers

Create Method Create new refund

To create a new refund, call the following API through HTTP POST. 

https://api.digiwallet.nl/refund

With the following parameters (* = required):

Variable Explanation Example
paymethodID* The ID of the payment method of the original transaction. Currently iDEAL and Bancontact are supported. Refer to the values below:
  • IDE: iDEAL
  • MRC: Bancontact
 IDE
transactionID* The ID of the original transaction. 12345678
amount* The amount to refund in eurocents. Note that this cannot exceed the amount of the original transaction, with an added 25,00 euros. 5000
description* Description for the consumer's bank statement. Order 12345 out of stock
internalNote Internal note for in the DigiWallet Backoffice. Refunded by Johnny

You will then get a JSON-encoded array response with the following content:

Key Value
status 0
message Refund successfully created
refundID ID of the created refund

Example raw response 

{"status":0,"message":"Refund successfully created","refundID":12345}


In case of one or more errors, you will get a JSON-encoded array response with the following content:

Key Value
status 1
message Validation failed
errors Nested JSON-encoded array of validation errors

Example

Key Value
transactionID Transaction not found.
description Description cannot be blank.

Example raw response 

{"status":1,"message":"Validation failed","errors":{"transactionID":["Transaction not found."],"description":["Description cannot be blank."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.

Delete Method Delete pending refund

To delete a refund that has not been confirmed yet, call the following API through HTTP DELETE. 

https://api.digiwallet.nl/refund/<paymethodID>/<transactionID>

The query string parameters are defined as follows (* = required):

Variable Explanation Example
paymethodID* The ID of the payment method used in creating the refund. IDE
transactionID* The ID of the original transaction used in creating the refund. 12345678

You will then get a JSON-encoded array response with the following content:

Key Value
status 0
message Refund successfully deleted

Example raw response 

{"status":0,"message":"Refund successfully deleted"}


In case of one or more errors, you will get a JSON-encoded array response with the following content:

Key Value
status 1
message Validation failed
errors Nested JSON-encoded array of validation errors

Example

Key Value
transactionID This refund has already moved to invoicing and can no longer be deleted.

Example raw response 

{"status":1,"message":"Validation failed","errors":{"transactionID":["This refund has already moved to invoicing and can no longer be deleted."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.