Skip to content

Token.io Refunds API (1.0.2)

Token.io Payments REST API 2.0

Token.io Support: support@token.io

The Token.io Payments API enables you to connect securely with banks. Using our API you can handle registration, posting, and retrieval of refunds associated with original transaction account information.
For more information see our developer documentation.

Download OpenAPI description
BNPP-refunds.json
BNPP-refunds.yaml
Languages
Servers
SwaggerHub API Auto Mocking
https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2
Token.io API server
https://api.token.io/v2

Refunds

Using these endpoints you can handle registration, posting, and retrieval of refunds associated with original transaction account information.

Operations

Register a debtor account for refund

Request

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).

Security
BasicAuth or Bearer
Bodyapplication/jsonrequired
One of:
bnppobject(BnppRegistrationPayload_bnpp)
curl -i -X POST \
  https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/refund/registrations \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "bnpp": {
      "appId": "myAppId",
      "appSecret": "myAppSecret",
      "signingKeyId": "mySigningKeyId",
      "tokenSigningKeyId": "123e4567-e89b-12d3-a456-426614174000",
      "debtor": {
        "iban": "GB82WEST12345698765432",
        "bic": "mybic",
        "name": "John Smith",
        "ultimateDebtorName": "John Smith"
      }
    }
  }'

Responses

Successful response

Bodyapplication/json
registrationBnppRegistrationPayload (object)(Registration)
One of:
Response
application/json
{
  "registration": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdDateTime": "2017-04-05T10:43:07.000+00:00",
    "product": "REFUND",
    "bnpp": { … }
  }
}

Retrieve refund registration information

Request

Retrieves the current refund registration information by registration id.

Security
BasicAuth or Bearer
Path
registrationIdstringrequired

The registration id.

Example: your registration id
curl -i -X GET \
  'https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/refund/registrations/your registration id' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
registrationBnppRegistrationPayload (object)(Registration)
One of:
Response
application/json
{
  "registration": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdDateTime": "2017-04-05T10:43:07.000+00:00",
    "product": "REFUND",
    "bnpp": { … }
  }
}

Delete refund registration information

Request

Deletes refund registration information by registration id.

Security
BasicAuth or Bearer
Path
registrationIdstringrequired

The registration id.

Example: your registration id
curl -i -X DELETE \
  'https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/refund/registrations/your registration id' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
object(EmptyResponse)
Response
application/json
{}

Retrieve refunds

Request

Retrieves a complete or filtered list of refunds.

Security
BasicAuth or Bearer
Query
limitinteger(int32)[ 1 .. 100 ]required

The maximum number of records to return.

Example: limit=10
offsetstring

The offset from the previous page.

startDatestring

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
endDatestring

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
curl -i -X GET \
  'https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/refunds?limit=10&offset=string&startDate=2010-01-01&endDate=2010-01-01' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
refundsArray of objects(Refund)
pagingobject(Paging)
Response
application/json
{
  "refunds": [
    { … }
  ],
  "paging": {
    "limit": 0,
    "offset": "string"
  }
}

Initiate a refund

Request

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.

Security
BasicAuth or Bearer
Bodyapplication/jsonrequired
initiationobject(RefundInitiation)required

The Initiation payload for the refund.

initiation.​descriptionstring

Description for the refund.

Example: "refund for some reason"
initiation.​refIdstringrequired

The reference id from the customer.

Example: "myRefId"
initiation.​amountobject(Amount)required
initiation.​amount.​valuestringrequired

The double amount in a string format.

Example: "10.23"
initiation.​amount.​currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"
initiation.​originalPaymentIdstringrequired

The original payment id from Token.io payments/transfers. This is required to initiate a refund. Token.io will check the original payment for the refund validation.

Example: "t:sdsds:sdsd"
initiation.​registrationIdstringrequired

The registraion id.

Example: "regId"
initiation.​localInstrumentstringrequired

ASPSP's payment service to be used for making a payment.

Enum"SEPA""SEPA_INSTANT""FASTER_PAYMENT"
Example: "SEPA_INSTANT"
initiation.​signaturestring

Base64 of the merchant signature over the payload returned by POST /refunds/signature. Token.io forwards it to the bank.

Example: "MEUCIQDx..."
curl -i -X POST \
  https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/refunds \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiation": {
      "description": "refund for some reason",
      "refId": "myRefId",
      "amount": {
        "value": "10.23",
        "currency": "EUR"
      },
      "originalPaymentId": "t:sdsds:sdsd",
      "registrationId": "regId",
      "localInstrument": "SEPA_INSTANT",
      "signature": "MEUCIQDx..."
    }
  }'

Responses

Successful response

Bodyapplication/json
refundobject(Refund)

The refund object.

Response
application/json
{
  "refund": {
    "id": "rf:12345abcd:abcd",
    "bankTransactionId": "1231423",
    "memberId": "m:123456abcd:abcd",
    "createdDateTime": "2017-04-05T10:43:07.000+00:00",
    "updatedDateTime": "2017-04-05T10:45:07.000+00:00",
    "status": "INITIATION_COMPLETED",
    "bankPaymentStatus": "ACPC",
    "statusReasonInformation": "The payment is settled on debtor side.",
    "initiation": { … }
  }
}

Build the payload a merchant has to sign for a refund

Request

Returns the provider payload the merchant has to sign before calling POST /refunds. Stateless: no refund is created and nothing is persisted by this call.
The merchant signs the returned payloadToSign and submits the signature back in the signature field of the initiation on the subsequent POST /refunds call.

Security
BasicAuth or Bearer
Bodyapplication/jsonrequired
initiationobject(RefundInitiation)required

The Initiation payload for the refund.

initiation.​descriptionstring

Description for the refund.

Example: "refund for some reason"
initiation.​refIdstringrequired

The reference id from the customer.

Example: "myRefId"
initiation.​amountobject(Amount)required
initiation.​amount.​valuestringrequired

The double amount in a string format.

Example: "10.23"
initiation.​amount.​currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"
initiation.​originalPaymentIdstringrequired

The original payment id from Token.io payments/transfers. This is required to initiate a refund. Token.io will check the original payment for the refund validation.

Example: "t:sdsds:sdsd"
initiation.​registrationIdstringrequired

The registraion id.

Example: "regId"
initiation.​localInstrumentstringrequired

ASPSP's payment service to be used for making a payment.

Enum"SEPA""SEPA_INSTANT""FASTER_PAYMENT"
Example: "SEPA_INSTANT"
initiation.​signaturestring

Base64 of the merchant signature over the payload returned by POST /refunds/signature. Token.io forwards it to the bank.

Example: "MEUCIQDx..."
curl -i -X POST \
  https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/refunds/signature \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiation": {
      "description": "refund for some reason",
      "refId": "myRefId",
      "amount": {
        "value": "10.23",
        "currency": "EUR"
      },
      "originalPaymentId": "t:sdsds:sdsd",
      "registrationId": "regId",
      "localInstrument": "SEPA_INSTANT",
      "signature": "MEUCIQDx..."
    }
  }'

Responses

Successful response

Bodyapplication/json
payloadToSignstring

Base64 of the provider payload the merchant has to sign.

Example: "eyJncm91cEhlYWRlciI6e319"
Response
application/json
{
  "payloadToSign": "eyJncm91cEhlYWRlciI6e319"
}

Retrieve a Refund

Request

Retrieves a refund by the id.

Security
BasicAuth or Bearer
Path
idstringrequired

The refund id.

Example: your refund id
curl -i -X GET \
  'https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/refunds/your refund id' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
refundobject(Refund)

The refund object.

Response
application/json
{
  "refund": {
    "id": "rf:12345abcd:abcd",
    "bankTransactionId": "1231423",
    "memberId": "m:123456abcd:abcd",
    "createdDateTime": "2017-04-05T10:43:07.000+00:00",
    "updatedDateTime": "2017-04-05T10:45:07.000+00:00",
    "status": "INITIATION_COMPLETED",
    "bankPaymentStatus": "ACPC",
    "statusReasonInformation": "The payment is settled on debtor side.",
    "initiation": { … }
  }
}

Retrieve all refunds by transfer

Request

Retrieves all the refunds associated with the given transfer.

Security
BasicAuth or Bearer
Path
idstringrequired

The transfer id.

Example: your transfer id
Query
limitinteger(int32)[ 1 .. 100 ]required

The maximum number of records to return.

Example: limit=10
offsetstring

The offset from the previous page.

curl -i -X GET \
  'https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/transfers/your transfer id/refunds?limit=10&offset=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
refundsArray of objects(Refund)
pagingobject(Paging)
Response
application/json
{
  "refunds": [
    { … }
  ],
  "paging": {
    "limit": 0,
    "offset": "string"
  }
}

Upload private key and certificate

Request

Uploads a private key and certificate.

Security
BasicAuth or Bearer
Bodyapplication/jsonrequired
uploadkeyAndCertificate (object) or keys (object)
One of:

The private key and certificate.

curl -i -X POST \
  https://virtserver.swaggerhub.com/token/token-refund-rest-api-bnpp/1.0.2/secrets/upload/key-and-certificate \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "upload": {
      "keyAndCertificate": {
        "privateKey": "xxxxxxxx",
        "certificate": "xxxxx",
        "certificateName": "QWAC_PSDGB-FCA-795904"
      }
    }
  }'

Responses

Successful response

Bodyapplication/json
keyIdstring

The unique identifier for the key.

Example: "XXXXXXX"
Response
application/json
{
  "keyId": "XXXXXXX"
}