Money Transfers

If your connection supports transfers, you can send money from your connected bank account to an IBAN. Whether a connection supports transfers is in the capabilities field of the Connections endpoint: when the list includes OUTGOING_TRANSFER, transfers can be made from that connection's accounts.

A transfer sent with an API key needs no e-mail verification code. The approval is your key's permission, the request signature and the request coming from an address on the key's IP allowlist. The transfer becomes SUBMITTED as soon as it is created and is queued for the bank. The bank decides the route (between your own accounts, within the same bank, FAST or EFT).

Endpoints

Every endpoint needs bank-connect:transfer. Your key decides the environment; do not send environment.

Signing a request with a body

Reads are signed as described in API Introduction. On POST requests, the SHA-256 digest of the body is sent in the Digest header and becomes the last line of the canonical string. The cURL examples on this page use the shell function below:

# lunixi-sign.sh — Usage: source lunixi-sign.sh; lunixi_sign POST "/api/v1/bank-connect/transfers" "$BODY"
LUNIXI_KEY_ID="mk_test_..."
LUNIXI_KEY_FILE="lunixi-signing.key"
 
lunixi_sign() {
  local method="$1" req_path="$2" body="$3"
  DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  NONCE=$(openssl rand -hex 16)
  if [ -n "$body" ]; then
    DIGEST="SHA-256=$(printf '%s' "$body" | openssl dgst -sha256 -binary | base64)"
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s\nDigest:%s' "$method" "$req_path" "$DATE" "$NONCE" "$DIGEST" > canonical.txt
  else
    DIGEST=""
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s' "$method" "$req_path" "$DATE" "$NONCE" > canonical.txt
  fi
  SIGNATURE=$(openssl pkeyutl -sign -inkey "$LUNIXI_KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
}

The PHP examples use PHP SDK 0.22.0 or later; $bankConnect->transfers() calls the endpoints on this page and signs every request.

Payment purposes

GET /api/v1/bank-connect/transfer-purposes?connectionId={connectionId}

Returns the payment purpose codes the bank accepts on this connection. You can put one of these codes in the transfer's paymentPurpose; without it the bank's default is used.

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "items": [
      { "code": "OTHER", "name": "Diğer", "order": 1 },
      { "code": "RENT", "name": "Kira", "order": 2 }
    ]
  },
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Codes differ between banks; read them from this endpoint instead of hard-coding them.

Creating a transfer

POST /api/v1/bank-connect/transfers

Any other body field (environment, merchantId …) gets 400 VALIDATION_ERROR.

source lunixi-sign.sh
REQ_PATH="/api/v1/bank-connect/transfers"
BODY='{"accountId":"00000000-0000-0000-0000-000000000100","receiverIban":"TR000000000000000000000000","receiverName":"Örnek Tedarik A.Ş.","amountMinor":150075,"description":"Invoice 2026-0042"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: payout-2026-0042" \
  --data-raw "$BODY"

The IBAN in the example is a placeholder; send an IBAN with valid check digits.

A successful response is 201:

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "transfer": {
      "id": "00000000-0000-0000-0000-000000002000",
      "connectionId": "00000000-0000-0000-0000-000000000010",
      "accountId": "00000000-0000-0000-0000-000000000100",
      "environment": "live",
      "status": "SUBMITTED",
      "rail": null,
      "amountMinor": 150075,
      "currency": "TRY",
      "sourceIbanMasked": "TR00 **** **** **** **** **00 00",
      "receiverIbanMasked": "TR00 **** **** **** **** **00 00",
      "receiverNameMasked": "Ö**** T****** A.Ş.",
      "receiverBankCode": "0000",
      "paymentPurpose": null,
      "description": "Invoice 2026-0042",
      "idempotencyKey": "payout-2026-0042",
      "failureCode": null,
      "outcomeUnknown": false,
      "initiatedVia": "API",
      "sanctionStatus": "NOT_SCREENED",
      "bankTransactionId": null,
      "bankState": null,
      "createdAt": "2026-01-01T07:00:00.000Z",
      "submittedAt": "2026-01-01T07:00:00.000Z",
      "completedAt": null,
      "failedAt": null,
      "returnedAt": null,
      "canceledAt": null,
      "otpExpiresAt": null
    },
    "stepUp": null,
    "replayed": false
  },
  "statusCode": 201,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Idempotency-Key

Every transfer request carries an Idempotency-Key so that the same transfer is never sent twice. The key is unique within your organization and environment.

• Derive the key from the payment record in your own system (for example payout-<your payment id>). Then a restart of your process still sends the same key for the same payment.
• On a timeout or a network error, resend the request with the same key and the same body. If the transfer was created, the existing one is returned; if not, it is created now.
• The SDKs generate a key when you do not pass one and reuse it on their own retries. The key used is in transfer.idempotencyKey in the response.

Tracking a transfer

The outcome of a transfer arrives in two ways:

• Webhook: the bank_transfer.created, bank_transfer.completed, bank_transfer.failed and bank_transfer.returned events. → Webhook Events › Transfer events
• Query: GET /api/v1/bank-connect/transfers/{transferId}. If you missed a webhook or have no endpoint, track the transfer with this endpoint.

What the statuses mean and how they change: Concepts › Transfer statuses.

Single transfer

GET /api/v1/bank-connect/transfers/{transferId} returns one transfer; data is the transfer object itself. An unknown transfer, or one that belongs to another organization or the other environment, returns 404 bank_connect.transfer.not_found.

source lunixi-sign.sh
REQ_PATH="/api/v1/bank-connect/transfers/00000000-0000-0000-0000-000000002000"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

Listing transfers

GET /api/v1/bank-connect/transfers lists transfers newest first. Transfers started in the panel and through the API are listed together (initiatedVia).

Paging rules are the same as on the read endpoints. → API Introduction › Pagination

Transfer with an unconfirmed outcome

When no definite answer comes from the bank (for example the bank did not reply in time), the transfer stays SUBMITTED and outcomeUnknown becomes true. In that case:

• Do not send the transfer again. The money may have left at the bank; a new transfer could pay twice.
• Lunixi confirms the outcome with the bank. When the transfer is settled its status becomes COMPLETED or FAILED and the matching webhook is sent.
• If the bank check shows that the transfer did not take place, failureCode is bank_connect.transfer.failed_after_bank_check. You can then send the same payment again with a new Idempotency-Key.

The transfer object

In transfer, exchange quote and exchange order responses, a field without a value is returned as null; the field is not left out. This differs from the "a field without a value is left out" rule of the read endpoints.

IBANs and the receiver name are returned masked only; the full IBAN and full name are never in a response. → Concepts › Masking

Errors

If the bank rejects the transfer, the request still answers 201; the transfer becomes FAILED later and the reason is in failureCode. → Error Codes › Transfer result codes