# Retrieve refunds

Retrieves a complete or filtered list of refunds.

Endpoint: GET /refunds
Version: 1.0.2
Security: BasicAuth, Bearer

## Query parameters:

  - `limit` (integer, required)
    The maximum number of records to return.
    Example: 10

  - `offset` (string)
    The offset from the previous page.

  - `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: "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: "2010-01-01"

## Response 200 fields (application/json):

  - `refunds` (array)

  - `refunds.id` (string, required)
    Token.io generated refund id.
    Example: "rf:12345abcd:abcd"

  - `refunds.bankTransactionId` (string)
    The transaction id from the bank side. Can be empty if it is not available from the bank side.
    Example: "1231423"

  - `refunds.memberId` (string, required)
    Token.io member id of the customer initiating this refund.
    Example: "m:123456abcd:abcd"

  - `refunds.createdDateTime` (string, required)
    The time when this refund object was created (in ISO 8601 format).
    Example: "2017-04-05T10:43:07.000+00:00"

  - `refunds.updatedDateTime` (string, required)
    The last update time for the current status, sub status, status reason information and authentication (in ISO 8601 format).
    Example: "2017-04-05T10:45:07.000+00:00"

  - `refunds.status` (string, required)
    The Token.io Refund Initiation Status.  INITIATION_PENDING - Token.io has received the refund initiation and the initiation passed Token.io validation.  INITIATION_PROCESSING - the refund is processing on the bank side. Status can be updated to one of INITIATION_COMPLETED, INITIATION_REJECTED or INITIATION_FAILED. If the status is never updated by the bank within certain period of time, the status will stay INITIATION_PROCESSING forever and the corresponding status reason information field will reflect this fact. INITIATION_COMPLETED - the refund initiation is successful. This does not guarantee the refund is settled. INITIATION_REJECTED - the refund is rejected by the bank. More details are shared in the corresponding status reason information.   INITIATION_FAILED - Token.io failed to create the initiation due to failures on the bank side, e.g. the bank is not available at the moment.  INITIATION_NO_FINAL_STATUS_AVAILABLE - The payment status has not been updated for some time and Token.io has stopped polling it. The recommended maximum polling time is 30 days. The status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days if the bank does not update the status. This is a final status, but it does not indicate success or failure. Please contact the bank to check the actual status of the payment.
    Enum: "INITIATION_PENDING", "INITIATION_PROCESSING", "INITIATION_COMPLETED", "INITIATION_REJECTED", "INITIATION_FAILED", "INITIATION_NO_FINAL_STATUS_AVAILABLE"

  - `refunds.bankPaymentStatus` (string)
    The raw bank status. This field could be empty if no payment status is available on bank side.
    Example: "ACPC"

  - `refunds.statusReasonInformation` (string)
    A human-readable description of the reason behind the status.
    Example: "The payment is settled on debtor side."

  - `refunds.initiation` (object)
    The Initiation payload for the refund.

  - `refunds.initiation.description` (string)
    Description for the refund.
    Example: "refund for some reason"

  - `refunds.initiation.refId` (string, required)
    The reference id from the customer.
    Example: "myRefId"

  - `refunds.initiation.amount` (object, required)

  - `refunds.initiation.amount.value` (string, required)
    The double amount in a string format.
    Example: "10.23"

  - `refunds.initiation.amount.currency` (string, required)
    The ISO 4217 three letter currency code.
    Example: "EUR"

  - `refunds.initiation.originalPaymentId` (string, required)
    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"

  - `refunds.initiation.registrationId` (string, required)
    The registraion id.
    Example: "regId"

  - `refunds.initiation.localInstrument` (string, required)
    ASPSP's payment service to be used for making a payment.
    Enum: "SEPA", "SEPA_INSTANT", "FASTER_PAYMENT"

  - `refunds.initiation.debtor` (any, required)
    The debtor information. Account information (one of) is required.

  - `refunds.initiation.creditor` (any, required)
    The creditor information. Account account information (one of) is required.

  - `paging` (object)

  - `paging.limit` (integer)
    The limit (maximum number of records to return) that was sent in the request. If the actual number of returned records is less then the limit, there are no more records left to fetch. The maximum allowed limit is 200. If the passed limit is bigger than this, it will be set to 200.

  - `paging.offset` (string)
    The offset for the next page.

## Response 400 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 401 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 403 fields (application/json):

  - `error` (object, required)
    The error returned when the member is not authorised to perform the given operation: PermissionDenied. This error message will be accompanied by the reason from the bank. Typically this means the access token has expired and the TPP needs the user to re-authenticate with the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 404 fields (application/json):

  - `error` (object, required)
    The error object returned when given payment cannot be found: Resource.NotFound.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The requested entity, the paymentID, was not found.
    Example: "pm2:12345abcd:abcde"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 429 fields (application/json):

  - `error` (object, required)
    Resource exhausted. Too many requests.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The maximum number of requests has been reached.
    Example: "Resource exhausted. Check quota."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 500 fields (application/json):

  - `error` (object)
    This could refer to either an error on Token.io’s end or an error on the bank side. When the bank reports a 5xx error, Token sets token-external-error = true as a header in the HTTP response, indicating that the "internal" error originates from the bank. When one of Token.io's internal services fails or when the bank reports a 4xx error, this header is not populated. The absence of this response header should be interpreted as token-external-error = false.

  - `error.errorCode` (string)
    This is a textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 501 fields (application/json):

  - `error` (object, required)
    The operation was not implemented/supported/enabled by the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The operation was not implemented/supported/enabled by the bank.
    Example: "Not implemented."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 503 fields (application/json):

  - `error` (object, required)
    Service is unavailable, likely due to a transient condition; this is usually corrected with a retry.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The service is unavailable, likely due to a transient condition; this is usually corrected with a retry.
    Example: "Unavailable."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"

## Response 504 fields (application/json):

  - `error` (object, required)
    The deadline expired before the operation could complete.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The deadline expired before the operation could complete.
    Example: "Deadline exceeded."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The Token.io trace id.
    Example: "5678912345"