> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lux-core.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fastoo Cross-Border Payments

> Create wallet, bank and SEPA payouts with the LuxCore Payments API

# Fastoo Cross-Border Payments

Create Fastoo payouts through the standard LuxCore Payments API. Use the destination format for the recipient and track the payment through the usual status endpoint and webhooks.

| Route | Destination |
| - | - |
| Fastoo wallet | Phone, email, national passport or reference ID |
| Bank | Saved beneficiary identifier or inline IBAN details |
| SEPA | Saved beneficiary identifier |

<Info>
  Contact your account manager to enable the route and confirm supported
  countries, currencies, limits and fees for your merchant. Availability depends
  on your merchant configuration and the recipient's eligibility.
</Info>

## Currency and Amounts

Use a currency enabled for your merchant and the requested payout route. These requests do not perform automatic currency conversion.

Payment `amount` is an integer in **minor units**, according to the currency's decimal precision. With two decimal places, `10000` means `100.00`. See the [balance guide](/guides/balance) for merchant balance information.

## Create a Fastoo Payout

Use `POST /api/v1/payments` with `X-API-Key`. [API v2](/authentication) accepts the same payment body with its HMAC authentication. The method is **`bank_transfer`**, including wallet payouts; there is no public `fastoo` method code or separate merchant transfer endpoint.

Required Fastoo routing fields:

| Field | Value |
| - | - |
| `type` | `withdrawal` or `withdrawal_pp` |
| `method` | `bank_transfer` |
| `amount` | Integer minor units |
| `currency` | Currency enabled for your merchant and requested route |
| `merchant_reference` | Your payment reference |
| `customer` | Customer information required by the [payment contract](/guides/payments) |
| `payout.fastooDestination` | Exactly one of the destination forms below |

<Warning>
  Do not combine `fastooDestination` with `bank_account`, `bank_code`,
  `account_type`, `beneficiary_tax_id`, `payid`, `payid_type` or `bsb`, even as
  empty strings. `payout.recipient_name` is optional for a typed Fastoo
  destination. Send only the documented destination fields.
</Warning>

### Fastoo Wallet

The following examples create the same **100.00 GEL** payout intent. Use a GEL route enabled for your merchant and an actual recipient reference; the values shown are illustrative.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.lux-core.io/api/v1/payments' \
    -H 'X-API-Key: your_api_key' \
    -H 'Content-Type: application/json' \
    -d '{
      "amount": 10000,
      "currency": "GEL",
      "method": "bank_transfer",
      "type": "withdrawal",
      "merchant_reference": "fastoo-wallet-order-001",
      "customer": {"name": "Example Recipient", "email": "recipient@example.com"},
      "payout": {
        "fastooDestination": {"kind": "wallet", "scheme": "reference_id", "value": "recipient_demo_001"}
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.lux-core.io/api/v1/payments",
      headers={"X-API-Key": "your_api_key"},
      json={
          "amount": 10000,
          "currency": "GEL",
          "method": "bank_transfer",
          "type": "withdrawal",
          "merchant_reference": "fastoo-wallet-order-001",
          "customer": {"name": "Example Recipient", "email": "recipient@example.com"},
          "payout": {
              "fastooDestination": {
                  "kind": "wallet", "scheme": "reference_id", "value": "recipient_demo_001"
              }
          },
      },
      timeout=30,
  )
  # Verify an ambiguous response before considering another creation attempt.
  response.raise_for_status()
  payment = response.json()
  print(payment["transaction_id"], payment["status"])
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.lux-core.io/api/v1/payments", {
    method: "POST",
    headers: { "X-API-Key": "your_api_key", "Content-Type": "application/json" },
    body: JSON.stringify({
      amount: 10000,
      currency: "GEL",
      method: "bank_transfer",
      type: "withdrawal",
      merchant_reference: "fastoo-wallet-order-001",
      customer: { name: "Example Recipient", email: "recipient@example.com" },
      payout: {
        fastooDestination: {
          kind: "wallet",
          scheme: "reference_id",
          value: "recipient_demo_001",
        },
      },
    }),
    signal: AbortSignal.timeout(30000),
  });
  // A timeout or 5xx response does not prove that creation was rejected.
  if (!response.ok)
    throw new Error(`Verify payout outcome: HTTP ${response.status}`);
  const payment = await response.json();
  console.log(payment.transaction_id, payment.status);
  ```
</CodeGroup>

For `kind: "wallet"`, send `scheme` and `value` using one of these forms:

| Scheme | `value` format |
| - | - |
| `phone` | 8–15 digits, without `+`, spaces or punctuation |
| `email` | Valid email address |
| `national_passport` | 6–12 digits |
| `reference_id` | 1–100 ASCII letters, digits, underscores or hyphens |

Use an identifier provided by the recipient. Valid syntax alone does not guarantee that the recipient can receive this payout.

### Bank and SEPA Destinations

Replace the wallet `payout` with **one** of the following. The surrounding payment fields remain the same; choose the currency supported by the selected account and rail.

For a saved Fastoo bank beneficiary:

```json theme={null}
{
  "fastooDestination": {
    "kind": "bank",
    "ibanAccountId": "123"
  }
}
```

For a saved SEPA beneficiary:

```json theme={null}
{
  "fastooDestination": {
    "kind": "sepa",
    "ibanAccountId": "123"
  }
}
```

`ibanAccountId` identifies a saved beneficiary available for your payout route. Supply it as a decimal **string** from `1` through `2147483647`; it is not a raw IBAN. Obtain the beneficiary identifier through your account manager. Inline SEPA beneficiaries are not accepted.

For an inline bank beneficiary:

```json theme={null}
{
  "fastooDestination": {
    "kind": "bank",
    "bank": {
      "iban": "GE29NB0000000101904917",
      "beneficiaryName": "Example Recipient",
      "beneficiaryBank": "Example Bank",
      "address": "Example recipient address",
      "swift": "EXAMPLEG",
      "reference": "invoice-001"
    }
  }
}
```

Use actual beneficiary data instead of these illustrative values. `iban` uses uppercase letters/digits, starts with a two-letter country code and has 15–34 characters. `swift` has 8 or 11 uppercase letters/digits. Name, bank and address are required nonblank strings of at most 200 characters; optional `reference` has at most 140. Do not send both `bank` and `ibanAccountId` or extra destination fields.

### Payment Status and Retries

A successful creation response returns `transaction_id` and `status`. Creation does not mean that the transfer has completed. Read `GET /api/v1/payments/{transaction_id}` and process standard [payment webhooks](/guides/webhooks).

<Warning>
  After a timeout or unknown result, preserve the original `merchant_reference`
  and any returned payment ID. Check the original payment or contact support
  before submitting a replacement. Reusing the same reference is not an
  unconditional retry guarantee. See [creation outcome
  errors](/errors/error-codes#payment_create_outcome_unknown).
</Warning>

## Incoming Payments

For an enabled incoming route, create a standard `deposit` or `deposit_pp` with `method: "bank_transfer"` and the configured currency. Do not include `payout.fastooDestination` on a deposit request. Display the instructions returned for that payment, including its exact amount and reference, to the payer.

Track the result through the payment status endpoint and webhooks. Use the [balance API](/guides/balance) to read your merchant balance. For an unconfirmed payment or unexpected balance, contact support with the payment ID and merchant reference.

## Troubleshooting

| Situation | Next action |
| - | - |
| `FASTOO_PAYOUT_NOT_READY` | Contact your account manager to confirm route availability for the requested currency |
| Invalid destination | Check the required fields and formats above; send exactly one destination form |
| Unsupported currency or limit | Confirm the currencies and limits enabled for your merchant |
| Pending payment or unknown creation result | Check the original payment and contact support before creating a replacement |

See the [payment error reference](/errors/error-codes) for standard errors. Share the payment ID, merchant reference and error code with support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.