# Build the payload a merchant has to sign for a refund

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.

Endpoint: POST /refunds/signature
Version: 1.0.2
Security: BasicAuth, Bearer

## Request fields (application/json):

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

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

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

  - `initiation.amount` (object, required)

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

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

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

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

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

  - `initiation.signature` (string)
    Base64 of the merchant signature over the payload returned by POST /refunds/signature. Token.io forwards it to the bank.
    Example: "MEUCIQDx..."

## Response 200 fields (application/json):

  - `payloadToSign` (string)
    Base64 of the provider payload the merchant has to sign.
    Example: "eyJncm91cEhlYWRlciI6e319"

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