Refunds

These endpoints allow you to handle registration, posting, and retrieval of refunds associated with original transaction account information.

Register a debtor account for refund

The POST /refund/registrations endpoint registers a debtor account for refund processing.
If the bank or provider returns any additional credentials for further refund payments, Token.io will store them in the Hardware Security Module (HSM).

SecurityBearer or BasicAuth
Request
Request Body schema: application/json
required
One of:
object (BnppRegistrationPayload_bnpp)
Responses
200

Successful response

400

The client specified an invalid argument

401

The authorisation information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a payment, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

post/refund/registrations
Request samples
application/json
{
  • "bnpp": {
    }
}
Response samples
application/json
{
  • "registration": {
    }
}

Retrieve refund registration information

The GET /refund/registrations/{registrationId} endpoint retrieves the current refund registration information by registration id.

SecurityBearer or BasicAuth
Request
path Parameters
registrationId
required
string

The registration id.

Example: your registration id
Responses
200

Successful response

400

The client specified an invalid argument

401

The authorisation information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a payment, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

get/refund/registrations/{registrationId}
Request samples 
Response samples 
application/json
{
  • "registration": {
    }
}
Delete refund registration information
The DELETE /refund/registrations/{registrationId} deletes refund registration information by registration id.


SecurityBearer or BasicAuth 
Request 
path Parameters
registrationId
required
string
The registration id.


 
 Example:  your registration id
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorisation information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a payment, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


delete/refund/registrations/{registrationId}
Request samples 
Response samples 
application/json
{ }
Initiate a refund
The POST /refunds endpoint initiates a refund. After the refund is settled, the refund status of the original transfer will be updated. 
 The debtor field can be optional if you're using the debtor in registration. The creditor field can be optional if the information is available in the original payment.


SecurityBearer or BasicAuth 
Request 
Request Body schema: application/json
required
required
object (RefundInitiation) 
The Initiation payload for the refund.


 
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a payment, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


post/refunds
Request samples 
application/json
{
  • "initiation": {
    }
}
Response samples 
application/json
{
  • "refund": {
    }
}
Get refunds
The GET /refunds endpoint retrieves a complete or filtered list of refunds.


SecurityBearer or BasicAuth 
Request 
query Parameters
limit
required
integer <int32>   [ 1 .. 200 ] 
The maximum number of records to return.


 
 Example:  limit=10
offset
string
The offset from the previous page.


 
 Example:  offset=LerV6Jmex
startDate
string
Lower bound for a refund creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only refunds created at or after the given date will be returned.


 
 Example:  startDate=2010-01-01
endDate
string
Upper bound for a refund creation date in the format 'YYYY-MM-DD' (UTC time zone). If specified, only refunds created at or before the given date will be returned.


 
 Example:  endDate=2010-01-01
ids
Array of strings
Filters refunds by their ids - returns only refunds with ids listed in this parameter.


 
 Example:  ids=rf:4QExXrhKTxfShBdcTeqFabqJJhUF:2gFUX1NDgpN&ids=rf:N5cJDFsQzVca3Qvr8kQocgEnjgX:2gFUX1NEdYA
invertIds
boolean
Invert ids query - returns only refunds with ids not listed in the ids parameter.


 
statuses
Array of arrays
Filters refunds by their statuses - returns only refunds with statuses listed in this parameter.


 
 Example:  statuses=INITIATION_COMPLETED&statuses=INITIATION_REJECTED
invertStatuses
boolean
Invert statuses query - returns only refunds with statuses not listed in the statuses parameter.


 
 Example:  invertStatuses=true
refIds
Array of strings
Filters refunds by their refId values - returns only refunds with refIds listed in this parameter.


 
 Example:  refIds=ShBdcTeqFabqJJhUF&refIds=N5cJDFsQzVca3Q
partial
boolean
Returns refunds in a partial format - with only id and status fields populated.


 
 Example:  partial=true
onBehalfOfIds
Array of strings
Filters payouts by their onBehalfOfId values - returns only payouts with the onBehalfOfId values specified in this parameter. This field is mandatory for unregulated TPPs.


 
 Example:  onBehalfOfIds=c5a863bc-86f2-4418-a26f-25b24c7983c7&onBehalfOfIds=6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a payment, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/refunds
Request samples 
Response samples 
application/json
{
  • "refunds": [
    ],
  • "paging": {
    }
}
Get a refund
The GET /refunds/{id} endpoint retrieves a given refund.


SecurityBearer or BasicAuth 
Request 
path Parameters
id
required
string
The refund id.


 
 Example:  your refund id
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a payment, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/refunds/{id}
Request samples 
Response samples 
application/json
{
  • "refund": {
    }
}
Get all refunds by transfer
The GET /transfers/{id}/refunds endpoint retrieves all refunds associated with a given transfer.


SecurityBearer or BasicAuth 
Request 
path Parameters
id
required
string
The transfer id.


 
 Example:  your transfer id
query Parameters
limit
required
integer <int32>   [ 1 .. 200 ] 
The maximum number of records to return.


 
 Example:  limit=10
offset
string
The offset from the previous page.


 
 Example:  offset=LerV6Jmex
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a payment, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


get/transfers/{id}/refunds
Request samples 
Response samples 
application/json
{
  • "refunds": [
    ],
  • "paging": {
    }
}
Upload a private key and certificate
The POST /secrets/upload/key-and-certificate endpoint uploads a private key and certificate. This is required if you process refunds through your own system and not through the Dashboard.


SecurityBearer or BasicAuth 
Request 
Request Body schema: application/json
required
keyAndCertificate (object) or keys (object)
 
Responses 
200
Successful response


400
The client specified an invalid argument


401
The authorization information is missing or invalid


403
Permission to access this endpoint is denied


404
The requested entity, such as a payment, was not found


429
Too many requests


500
An unexpected or internal server error


501
The operation was not implemented


503
Service is unavailable


504
Gateway has timed out


post/secrets/upload/key-and-certificate
Request samples 
application/json
{
  • "upload": {
    }
}
Response samples 
application/json
{
  • "keyId": "XXXXXXX"
}
➔ Next to Payouts