# Retrieve a Refund

Retrieves a refund by the id.

Endpoint: GET /refunds/{id}
Version: 1.0.2
Security: BasicAuth, Bearer

## Path parameters:

  - `id` (string, required)
    The refund id.
    Example: "your refund id"

## Response 200 fields (application/json):

  - `refund` (object)
    The refund object.

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

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

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

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

  - `refund.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"

  - `refund.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"

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

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

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

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

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

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

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

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

  - `refund.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"

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

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

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

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

## 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"