POST /transfer

Initiate a new wire transfer from the exchange’s bank account, typically to a merchant.

The exchange’s bank account is not included in the request, but instead derived from the username in the Authorization header and/or the request base URL.

To make the API idempotent, the client must include a nonce. Requests with the same nonce are rejected unless the request is the same.

Request:

interface TransferRequest {
  // Nonce to make the request idempotent.  Requests with the same
  // request_uid that differs in any of the other fields
  // are rejected.
  request_uid: HashCode;

  // Amount to transfer.
  amount: Amount;

  // Base URL of the exchange.  Shall be included by the bank gateway
  // in the appropriate section of the wire transfer details.
  exchange_base_url: string;

  // Optional additional metadata to be stored in the transaction.
  // Must match [a-zA-Z0-9-.:]{1, 40}
  // @since **v5**
  metadata?: string;

  // Wire transfer identifier chosen by the exchange,
  // used by the merchant to identify the Taler order(s)
  // associated with this wire transfer.
  wtid: ShortHashCode;

  // The recipient's account identifier as a full payto URI.
  credit_account: string;
}

Response:

200 OK:

The request has been correctly handled, so the funds have been transferred to the recipient’s account. The body is a TransferResponse.

400 Bad request:

Request malformed. The bank replies with an ErrorDetail object.

401 Unauthorized:

Authentication failed, likely the credentials are wrong.

404 Not found:

The endpoint is wrong or the user name is unknown. The bank replies with an ErrorDetail object.

409 Conflict:

• TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED: an operation with the same request_uid but different details has been submitted before.

• TALER_EC_BANK_TRANSFER_WTID_REUSED: an operation with the same wtid but a different request_uid has been submitted before.

Details:

interface TransferResponse {
  // Timestamp that indicates when the wire transfer will be executed.
  // In cases where the wire transfer gateway is unable to know when
  // the wire transfer will be executed, the time at which the request
  // has been received and stored will be returned.
  // The purpose of this field is for debugging (humans trying to find
  // the transaction) as well as for taxation (determining which
  // time period a transaction belongs to).
  timestamp: Timestamp;

  // Opaque ID of the wire transfer initiation performed by the bank.
  // It is different from the /history endpoints row_id.
  row_id: SafeUint64;
}