# Create a buy instruction

Declares an incoming fiat payment under an id you choose, and returns the memo to quote in
that payment's reference field so the funds can be attributed and the RLUSD minted to the
wallet you named.

You generate the UUID for {id} client-side and it becomes the instruction's identity.
Reusing an id that already exists is rejected with a 409 carrying code
FIAT_INSTRUCTION_ALREADY_EXISTS.

Only a CRYPTO destination may be created here. Redemption (FIAT) instructions are
created by Ripple when your redemption is registered, and are read-only to you.

> Put the memo verbatim into the payment's reference field, and nothing else. A
> RIPxxxxxxx wallet ripId token in the payment's free text takes precedence over a memo
> during matching, which would credit that wallet and leave this instruction UNUSED.

Endpoint: PUT /v1/stablecoin/fiat-instructions/{id}
Version: 1.0.0
Security: oauth2

## Path parameters:

  - `id` (string, required)
    The id you are creating the instruction under, as a UUID you choose.

## Request fields (application/json):

  - `currency` (string, required)
    ISO-4217 fiat currency code of the payment you intend to send.
    Example: "USD"

  - `destination` (object, required)
    Destination for the resulting RLUSD. type must be CRYPTO and walletRipId must be
supplied; anything else is rejected with a 400 carrying code INVALID_REQUEST_BODY.

  - `destination.type` (string, required)
    CRYPTO for a buy instruction - the RLUSD is minted to one of your wallets. FIAT only
ever appears on a redemption instruction, which Ripple creates for you and which cannot
be created through this API.
    Enum: "CRYPTO", "FIAT"

  - `destination.walletRipId` (string,null)
    Destination wallet ripId (e.g. RIP0000001). Required when type is CRYPTO;
absent when type is FIAT. Resolve valid ids with
[List wallets](#operation/listWallets).
    Example: "RIP0000001"

## Response 200 fields (application/json):

  - `id` (string, required)
    Instruction identifier. You supply it in the PUT path for a buy instruction; Ripple
generates it for a redemption instruction.

  - `memo` (string, required)
    Routing memo that correlates a fiat payment back to this instruction - quote it verbatim
in the payment's reference field so the funds can be attributed. Assigned by Ripple and
globally unique: RL followed by 14 Crockford base32 characters, 16 in total. Crockford
base32 excludes I, L, O and U to avoid transcription ambiguity.
    Example: "RL7Q3K9ZP2MTX4VB"

  - `currency` (string,null)
    ISO-4217 fiat currency code. Always present on a buy instruction. May be absent on a
redemption instruction whose originating fiat payment carries no currency.
    Example: "USD"

  - `destination` (object, required)
    Where the RLUSD goes once the instruction is claimed.

  - `destination.type` (string, required)
    CRYPTO for a buy instruction - the RLUSD is minted to one of your wallets. FIAT only
ever appears on a redemption instruction, which Ripple creates for you and which cannot
be created through this API.
    Enum: same as `destination.type` (2 values)

  - `destination.walletRipId` (string,null)
    Destination wallet ripId (e.g. RIP0000001). Required when type is CRYPTO;
absent when type is FIAT. Resolve valid ids with
[List wallets](#operation/listWallets).
    Example: "RIP0000001"

  - `status` (string, required)
    Lifecycle status. A new instruction is UNUSED and never expires; it becomes USED when
its fiat payment claims it, or CANCELED when Ripple cancels the payment behind it. Both
are terminal.

DELETED exists on the underlying record but is never served: the reads exclude deleted
instructions outright, so a deleted instruction returns
404 FIAT_INSTRUCTION_NOT_FOUND rather than a DELETED status.
    Enum: "UNUSED", "USED", "DELETED", "CANCELED"

  - `createdAt` (string, required)
    Timestamp when the instruction was created

  - `bankDetails` (object)
    The Ripple bank account to wire the fiat to. Resolved from the default bank account
registered against your stablecoin product, so it is the same on every instruction
rather than unique to one.

Absent when your account has no active default bank account on file, when that account
is not yet linked to a Ripple receiving bank, or when the details could not be
retrieved. The instruction and its memo are returned either way, so treat the field as
optional. [Get bank details](#operation/getFiatBankDetails) serves the same object on
its own and, unlike this field, reports why it is unavailable.

  - `bankDetails.bankName` (string, required)
    Name of the bank holding the account. May be an empty string.
    Example: "ABC Bank"

  - `bankDetails.accountName` (string, required)
    Name the account is held under - the Ripple legal entity you are paying. May be an empty
string.
    Example: "RIPPLE LABS CAYMAN LTD."

  - `bankDetails.accountNumber` (string)
    Account number to wire to.
    Example: "000000"

  - `bankDetails.iban` (string)
    IBAN to wire to, for accounts identified that way.

  - `bankDetails.swiftBicCode` (string)
    Example: "ABCBUS33XXX"

  - `bankDetails.routingNumber` (string)
    Example: "0000"

  - `bankDetails.reference` (string)
    Reference Ripple wants quoted on transfers to this account. Distinct from the
instruction's memo, which is what actually attributes the payment - send both.

  - `bankDetails.bankAddress` (object)
    Postal address of the bank account.

  - `bankDetails.bankAddress.street` (string)
    Street address. Where the bank's address is recorded over two lines, both are returned
here joined by , .
    Example: "1 Example Street"

  - `bankDetails.bankAddress.city` (string)
    Example: "Singapore"

  - `bankDetails.bankAddress.state` (string)
    State, province or region.
    Example: "Singapore"

  - `bankDetails.bankAddress.zipCode` (string)
    Example: "000000"

  - `bankDetails.bankAddress.country` (string)
    Example: "Singapore"

## Response 400 fields (application/problem+json):

  - `type` (string)
    URI reference identifying the problem type

  - `title` (string)
    Short, human-readable summary of the problem

  - `status` (integer)
    HTTP status code

  - `code` (string)
    Machine-readable error code
    Enum: "TRANSACTION_NOT_FOUND", "TRANSACTION_INVALID_STATUS_TRANSITION", "TRANSACTION_DESTINATION_TYPE_IMMUTABLE", "FIAT_INSTRUCTION_NOT_FOUND", "FIAT_INSTRUCTION_ALREADY_EXISTS", "FIAT_INSTRUCTION_INVALID_STATUS_TRANSITION", "STABLECOIN_BANK_DETAILS_NOT_FOUND", "WALLET_NOT_FOUND", "WALLET_NOT_APPROVED", "FORBIDDEN", "UPSTREAM_UNAVAILABLE", "INVALID_REQUEST_BODY", "UNKNOWN_EXCEPTION"