Payments Guide

This guide covers everything you need to know about creating and managing payments through the LuxCore API.

Response Metadata

Merchant custom fields supplied in the creation request’s metadata are returned in payment responses. They do not grant device access or override processing policy. Server fields such as expiry, payment type and the public commission total take precedence when names overlap. Payment responses expose the documented merchant fields. Use your own references to link payments to orders.

Payment Types

LuxCore supports four payment types:

Type	Direction	Description
`deposit`	Inbound	Customer pays to merchant (checkout)
`withdrawal`	Outbound	Merchant pays to customer/vendor (payout)
`deposit_pp`	Inbound	Deposit with hosted payment page
`withdrawal_pp`	Outbound	Withdrawal with hosted payment page

Payment Methods

Availability and processing times depend on the route enabled for your merchant. The times below are indicative, not completion guarantees. Use the returned payment instructions and expiry.

Method	Code	Deposit	Withdrawal	Processing Time
SPEI	`spei`	✅	✅	Up to 30 min
OXXO	`oxxo`	✅	❌	Up to 30 min
Card	`card`	✅	❌	Up to 30 min
Bank Transfer	`bank_transfer`	✅	✅	Up to 30 min
Cash	`cash`	✅	❌	Up to 30 min
Crypto	`crypto`	✅	✅	Up to 30 min
PayID	`payid`	✅	✅	Up to 10 min
iPay	`ipay`	✅	❌	Instant (redirect)

Supported Payment Currencies

Currency	Code	Country	Common Payment Method
Argentine Peso	`ARS`	Argentina	`bank_transfer`
Australian Dollar	`AUD`	Australia	`bank_transfer`, `payid`
Mexican Peso	`MXN`	Mexico	`spei`
Sri Lankan Rupee	`LKR`	Sri Lanka	`ipay`
Turkish Lira	`TRY`	Turkey	`bank_transfer`
Uruguayan Peso	`UYU`	Uruguay	`bank_transfer`

All amounts are in minor units (centavos, cents). For example, to charge 1,000.00 ARS, pass amount: 100000. Passing 1000 would create a payment for only 10.00 ARS.

Creating a Deposit (Customer Payment)

When a customer needs to pay you:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "description": "Order #ABC123",
    "customer": {
      "name": "Maria Garcia",
      "email": "maria@example.com",
      "phone": "+5491112345678"
    },
    "metadata": {
      "order_id": "abc123",
      "source": "web"
    }
  }'

import requests

payment = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 150000,  # 1500.00 ARS (amount in centavos)
        "currency": "ARS",
        "method": "bank_transfer",
        "type": "deposit",
        "merchant_reference": "order_abc123",
        "description": "Order #ABC123",
        "customer": {
            "name": "Maria Garcia",
            "email": "maria@example.com",
            "phone": "+5491112345678"
        },
        "metadata": {
            "order_id": "abc123",
            "source": "web"
        }
    }
)

Response (ARS)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "ARS",
  "method": "bank_transfer",
  "type": "deposit",
  "bank_details": {
    "amount": "150000",
    "purpose": "Payment pay_1234567890_abcdefgh",
    "currency": "ARS",
    "bank_name": "Banco Nacion",
    "swift_code": null,
    "account_holder": "LuxCore Platform S.A.",
    "account_number": "0110012345678901234567"
  },
  "created_at": "2025-01-21T10:30:00Z"
}

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "MXN",
    "method": "spei",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "description": "Order #ABC123",
    "customer": {
      "name": "Maria Garcia",
      "email": "maria@example.com",
      "phone": "+525551234567"
    },
    "metadata": {
      "order_id": "abc123",
      "source": "web"
    }
  }'

import requests

payment = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 150000,  # $1,500.00 MXN
        "currency": "MXN",
        "method": "spei",
        "type": "deposit",
        "merchant_reference": "order_abc123",
        "description": "Order #ABC123",
        "customer": {
            "name": "Maria Garcia",
            "email": "maria@example.com",
            "phone": "+525551234567"
        },
        "metadata": {
            "order_id": "abc123",
            "source": "web"
        }
    }
)

Response (MXN)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "MXN",
  "method": "spei",
  "type": "deposit",
  "bank_details": {
    "amount": "150000",
    "purpose": "Payment pay_1234567890_abcdefgh",
    "currency": "MXN",
    "bank_name": "STP",
    "swift_code": null,
    "account_holder": "LuxCore Platform S.A. de C.V.",
    "account_number": "646180157000000001"
  },
  "created_at": "2025-01-21T10:30:00Z"
}

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "UYU",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "description": "Order #ABC123",
    "customer": {
      "name": "Maria Garcia",
      "email": "maria@example.com",
      "phone": "+59891234567"
    },
    "metadata": {
      "order_id": "abc123",
      "source": "web"
    }
  }'

import requests

payment = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 150000,  # $1,500.00 UYU
        "currency": "UYU",
        "method": "bank_transfer",
        "type": "deposit",
        "merchant_reference": "order_abc123",
        "description": "Order #ABC123",
        "customer": {
            "name": "Maria Garcia",
            "email": "maria@example.com",
            "phone": "+59891234567"
        },
        "metadata": {
            "order_id": "abc123",
            "source": "web"
        }
    }
)

Response (UYU)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "UYU",
  "method": "bank_transfer",
  "type": "deposit",
  "bank_details": {
    "amount": "150000",
    "purpose": "Payment pay_1234567890_abcdefgh",
    "currency": "UYU",
    "bank_name": "BROU",
    "swift_code": null,
    "account_holder": "LuxCore Platform S.A.",
    "account_number": "001234567890"
  },
  "created_at": "2025-01-21T10:30:00Z"
}

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "AUD",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "description": "Order #ABC123",
    "customer": {
      "name": "James Smith",
      "email": "james@example.com",
      "phone": "+61412345678"
    },
    "metadata": {
      "order_id": "abc123",
      "source": "web"
    }
  }'

import requests

payment = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 150000,  # $1,500.00 AUD (amount in cents)
        "currency": "AUD",
        "method": "bank_transfer",
        "type": "deposit",
        "merchant_reference": "order_abc123",
        "description": "Order #ABC123",
        "customer": {
            "name": "James Smith",
            "email": "james@example.com",
            "phone": "+61412345678"
        },
        "metadata": {
            "order_id": "abc123",
            "source": "web"
        }
    }
)

Response (AUD - Bank Transfer)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "AUD",
  "method": "bank_transfer",
  "type": "deposit",
  "bank_details": {
    "amount": "150000",
    "purpose": "Payment pay_1234567890_abcdefgh",
    "currency": "AUD",
    "bank_name": "Commonwealth Bank",
    "swift_code": "CTBAAU2S",
    "account_holder": "LuxCore Platform Pty Ltd",
    "bsb": "062-000",
    "account_number": "12345678"
  },
  "created_at": "2026-02-18T10:30:00Z"
}

Alternatively, use PayID for a faster deposit experience:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "AUD",
    "method": "payid",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "description": "Order #ABC123",
    "customer": {
      "name": "James Smith",
      "email": "james@example.com",
      "phone": "+61412345678"
    },
    "metadata": {
      "order_id": "abc123",
      "source": "web"
    }
  }'

import requests

payment = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 150000,  # $1,500.00 AUD (amount in cents)
        "currency": "AUD",
        "method": "payid",
        "type": "deposit",
        "merchant_reference": "order_abc123",
        "description": "Order #ABC123",
        "customer": {
            "name": "James Smith",
            "email": "james@example.com",
            "phone": "+61412345678"
        },
        "metadata": {
            "order_id": "abc123",
            "source": "web"
        }
    }
)

Response (AUD - PayID)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "AUD",
  "method": "payid",
  "type": "deposit",
  "payid_details": {
    "amount": "150000",
    "purpose": "Payment pay_1234567890_abcdefgh",
    "currency": "AUD",
    "payid": "pay-1234567890@lux-core.io",
    "payid_type": "email",
    "payid_name": "LuxCore Platform Pty Ltd",
    "reference": "LXC-ABC123"
  },
  "created_at": "2026-02-18T10:30:00Z"
}

PayID uses Australia’s New Payments Platform (NPP) for near-instant settlement. The customer sends funds to the provided PayID identifier (email, phone, or ABN) through their banking app. PayID deposits typically settle within minutes.

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "TRY",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "description": "Order #ABC123",
    "customer": {
      "name": "Mehmet Yilmaz",
      "email": "mehmet@example.com",
      "phone": "+905551234567"
    },
    "metadata": {
      "order_id": "abc123",
      "source": "web"
    }
  }'

import requests

payment = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 150000,  # ₺1,500.00 TRY (amount in kurus)
        "currency": "TRY",
        "method": "bank_transfer",
        "type": "deposit",
        "merchant_reference": "order_abc123",
        "description": "Order #ABC123",
        "customer": {
            "name": "Mehmet Yilmaz",
            "email": "mehmet@example.com",
            "phone": "+905551234567"
        },
        "metadata": {
            "order_id": "abc123",
            "source": "web"
        }
    }
)

Response (TRY)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "TRY",
  "method": "bank_transfer",
  "type": "deposit",
  "bank_details": {
    "amount": "150000",
    "purpose": "Payment pay_1234567890_abcdefgh",
    "currency": "TRY",
    "bank_name": "Turkish Bank",
    "swift_code": null,
    "account_holder": "LuxCore Platform",
    "account_number": "TR000000000000000000000000"
  },
  "created_at": "2026-05-06T10:30:00Z"
}

TRY uses standard minor units: 100 equals ₺1.00. Available payment methods can depend on your merchant configuration; use bank_transfer unless your account manager enables another TRY rail.

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "LKR",
    "method": "ipay",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "description": "Order #ABC123",
    "customer": {
      "name": "Kamal Perera",
      "email": "kamal@example.com",
      "phone": "+94771234567"
    },
    "metadata": {
      "order_id": "abc123",
      "source": "web"
    }
  }'

import requests

payment = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 150000,  # Rs. 1,500.00 LKR (amount in cents)
        "currency": "LKR",
        "method": "ipay",
        "type": "deposit",
        "merchant_reference": "order_abc123",
        "description": "Order #ABC123",
        "customer": {
            "name": "Kamal Perera",
            "email": "kamal@example.com",
            "phone": "+94771234567"
        },
        "metadata": {
            "order_id": "abc123",
            "source": "web"
        }
    }
)

Response (LKR)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "LKR",
  "method": "ipay",
  "type": "deposit",
  "merchant_reference": "order_abc123",
  "created_at": "2025-11-22T10:30:00Z",
  "ipay_checkout": {
    "checkout_url": "https://checkout.ipay.lk/pay/abc123",
    "form_action": "https://sandbox.ipay.lk/listener",
    "form_method": "POST",
    "checkout_params": {
      "merchantId": "LUXCORE",
      "amount": "1500.00",
      "currency": "LKR",
      "referenceNo": "pay_1234567890_abcdefgh",
      "responseUrl": "https://api.lux-core.io/api/v1/providers/ipay/callback",
      "checkValue": "a1b2c3..."
    },
    "payment_schemes": ["VISA", "MC", "IPAY", "LQR"],
    "redirect_required": true
  }
}

Optionally, restrict the checkout to a specific payment scheme:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "LKR",
    "method": "ipay",
    "type": "deposit",
    "merchant_reference": "order_visa_only",
    "customer": {
      "name": "Kamal Perera",
      "email": "kamal@example.com"
    },
    "ipay": {
      "payment_method": "VISA"
    }
  }'

Available payment schemes for iPay:

VISA — Visa cards
MC — Mastercard
IPAY — iPay App
LQR — LankaQR (scan-to-pay)

Pass ipay.payment_method to restrict the checkout to a single scheme. If omitted, all available schemes are shown to the customer.

iPay deposits use a redirect or form-based flow. After creating the payment, submit a form to ipay_checkout.form_action with ipay_checkout.checkout_params, or redirect the customer to ipay_checkout.checkout_url. The customer completes payment on the hosted checkout page, and status updates are delivered via webhooks.

iPay Integration Details

Checkout Flow

Create a payment via POST /payments with method: "ipay" and currency: "LKR"
The response includes an ipay_checkout object — submit a form to ipay_checkout.form_action with ipay_checkout.checkout_params, or redirect to ipay_checkout.checkout_url
The customer completes payment on the iPay hosted checkout page (Visa, Mastercard, LankaQR, or iPay App)
iPay sends a server-to-server callback to confirm payment status
You receive a webhook (payment.completed or payment.failed) with the final status

Response Fields

Field	Type	Description
`ipay_checkout`	object	iPay checkout details for completing payment
`ipay_checkout.checkout_url`	string	URL to redirect the customer for payment
`ipay_checkout.form_action`	string	Form action URL for POST-based checkout
`ipay_checkout.form_method`	string	HTTP method for form submission (`POST`)
`ipay_checkout.checkout_params`	object	Parameters to include in the form submission
`ipay_checkout.payment_schemes`	string[]	Available payment schemes (e.g., `VISA`, `MC`, `IPAY`, `LQR`)
`ipay_checkout.redirect_required`	boolean	Whether a redirect/form submission is required
`status`	string	Initial status is `processing`

Limits

Parameter	Value
Minimum amount	100 (Rs. 1.00 LKR)
Currency	LKR only
Withdrawals	Not supported

iPay Callback Statuses

iPay reports three transaction statuses via server-to-server callback:

iPay Status	Code	LuxCore Status	Description
Accepted	`A`	`completed`	Payment successful, funds transferred
Pending	`P`	`processing`	Funds deducted, transfer pending (end-of-day settlement)
Declined	`D`	`failed`	Payment declined by iPay or card issuer

Pending (P) status: In rare cases, iPay may report a “Pending” status, meaning the customer’s funds have been deducted but the transfer to the merchant is scheduled for end-of-day batch settlement. The system monitors these payments and auto-cancels them if unresolved after 24 hours.

Fastoo Cross-Border Routes

For Fastoo wallet, bank and SEPA payouts, use method: "bank_transfer" with payout.fastooDestination. Use a currency enabled for your merchant and route; these requests do not perform automatic currency conversion. See Fastoo Cross-Border Payments for destination formats, request examples and payment status handling. The legacy bank-account payout fields below do not apply to typed Fastoo destinations.

Creating a Withdrawal (Payout)

To send money to a beneficiary:

customer vs payout: For withdrawals, both objects refer to the recipient of the funds.

customer — personal contact information (name, email, phone) for identification and communication
payout — destination details for the transfer (account number, bank code, reference)

Payout Fields

These fields describe legacy bank payouts. For a typed Fastoo payout, fastooDestination replaces the legacy destination fields and recipient_name is optional; see the Fastoo contract.

Field	Required	Description	Example
`recipient_name`	Yes	Full name of the beneficiary (must match bank account holder)	`"Juan Perez Martinez"`
`bank_account`	Yes	Bank account number. CBU/CVU (22 digits) for ARS, CLABE (18 digits) for MXN, account number for UYU, account number (6-10 digits) for AUD	`"0110012345678901234567"`
`bank_code`	No	Bank code. Required for MXN/SPEI. For AUD, use BSB (6 digits, format `XXX-XXX`)	`"002"`
`account_type`	No	Account type	`"checking"`
`beneficiary_tax_id`	No	Beneficiary tax ID (RFC, RUC, CUIT, ABN)	`"20-12345678-9"`
`description`	No	Purpose of the payout	`"Salary January 2025"`
`reference`	No	Merchant-provided tracking reference. If not provided, system generates one automatically	`"PAYOUT-JAN-001"`
`payid`	No	PayID identifier (email, phone, or ABN). Required when `method` is `payid` for AUD withdrawals	`"james@example.com"`
`payid_type`	No	Type of PayID: `email`, `phone`, or `abn`. Required when `payid` is provided	`"email"`

ARS (Argentina)
MXN (Mexico)
UYU (Uruguay)
AUD (Australia)

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "withdrawal",
    "merchant_reference": "payout_vendor_001",
    "description": "Payout January 2025",
    "customer": {
      "name": "Juan Perez Martinez",
      "email": "juan.perez@example.com",
      "phone": "+5491112345678"
    },
    "payout": {
      "recipient_name": "Juan Perez Martinez",
      "bank_account": "0110012345678901234567"
    }
  }'

payout = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 250000,
        "currency": "ARS",
        "method": "bank_transfer",
        "type": "withdrawal",
        "merchant_reference": "payout_vendor_001",
        "description": "Payout January 2025",
        "customer": {
            "name": "Juan Perez Martinez",
            "email": "juan.perez@example.com",
            "phone": "+5491112345678"
        },
        "payout": {
            "recipient_name": "Juan Perez Martinez",
            "bank_account": "0110012345678901234567"
        }
    }
)

Response (ARS Withdrawal)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "pending",
  "amount": 250000,
  "currency": "ARS",
  "method": "bank_transfer",
  "type": "withdrawal",
  "merchant_reference": "payout_vendor_001",
  "payout": {
    "recipient_name": "Juan Perez Martinez",
    "bank_account": "0110012345678901234567",
    "status": "pending"
  },
  "created_at": "2025-01-21T10:30:00Z"
}

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "MXN",
    "method": "spei",
    "type": "withdrawal",
    "merchant_reference": "payout_vendor_001",
    "description": "Payout January 2025",
    "customer": {
      "name": "Juan Perez Martinez",
      "email": "juan.perez@example.com",
      "phone": "+525551234567"
    },
    "payout": {
      "recipient_name": "Juan Perez Martinez",
      "bank_account": "012345678901234567",
      "bank_code": "002",
      "reference": "PAYOUT-JAN-001"
    }
  }'

payout = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 250000,
        "currency": "MXN",
        "method": "spei",
        "type": "withdrawal",
        "merchant_reference": "payout_vendor_001",
        "description": "Payout January 2025",
        "customer": {
            "name": "Juan Perez Martinez",
            "email": "juan.perez@example.com",
            "phone": "+525551234567"
        },
        "payout": {
            "recipient_name": "Juan Perez Martinez",
            "bank_account": "012345678901234567",
            "bank_code": "002",
            "reference": "PAYOUT-JAN-001"
        }
    }
)

Response (MXN Withdrawal)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "pending",
  "amount": 250000,
  "currency": "MXN",
  "method": "spei",
  "type": "withdrawal",
  "merchant_reference": "payout_vendor_001",
  "payout": {
    "recipient_name": "Juan Perez Martinez",
    "clabe": "012345678901234567",
    "bank_code": "002",
    "status": "pending"
  },
  "created_at": "2025-01-21T10:30:00Z"
}

For MXN/SPEI withdrawals, the response returns clabe instead of bank_account in the payout object. This matches the Mexican banking convention where the 18-digit account identifier is called CLABE.

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "UYU",
    "method": "bank_transfer",
    "type": "withdrawal",
    "merchant_reference": "payout_vendor_001",
    "description": "Payout January 2025",
    "customer": {
      "name": "Juan Perez Martinez",
      "email": "juan.perez@example.com",
      "phone": "+59891234567"
    },
    "payout": {
      "recipient_name": "Juan Perez Martinez",
      "bank_account": "001234567890"
    }
  }'

payout = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 250000,
        "currency": "UYU",
        "method": "bank_transfer",
        "type": "withdrawal",
        "merchant_reference": "payout_vendor_001",
        "description": "Payout January 2025",
        "customer": {
            "name": "Juan Perez Martinez",
            "email": "juan.perez@example.com",
            "phone": "+59891234567"
        },
        "payout": {
            "recipient_name": "Juan Perez Martinez",
            "bank_account": "001234567890"
        }
    }
)

Response (UYU Withdrawal)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "pending",
  "amount": 250000,
  "currency": "UYU",
  "method": "bank_transfer",
  "type": "withdrawal",
  "merchant_reference": "payout_vendor_001",
  "payout": {
    "recipient_name": "Juan Perez Martinez",
    "bank_account": "001234567890",
    "status": "pending"
  },
  "created_at": "2025-01-21T10:30:00Z"
}

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "AUD",
    "method": "bank_transfer",
    "type": "withdrawal",
    "merchant_reference": "payout_vendor_001",
    "description": "Payout February 2026",
    "customer": {
      "name": "James Smith",
      "email": "james@example.com",
      "phone": "+61412345678"
    },
    "payout": {
      "recipient_name": "James Smith",
      "bank_account": "12345678",
      "bank_code": "062-000"
    }
  }'

payout = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 250000,  # $2,500.00 AUD
        "currency": "AUD",
        "method": "bank_transfer",
        "type": "withdrawal",
        "merchant_reference": "payout_vendor_001",
        "description": "Payout February 2026",
        "customer": {
            "name": "James Smith",
            "email": "james@example.com",
            "phone": "+61412345678"
        },
        "payout": {
            "recipient_name": "James Smith",
            "bank_account": "12345678",
            "bank_code": "062-000"
        }
    }
)

Response (AUD Bank Transfer Withdrawal)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "pending",
  "amount": 250000,
  "currency": "AUD",
  "method": "bank_transfer",
  "type": "withdrawal",
  "merchant_reference": "payout_vendor_001",
  "payout": {
    "recipient_name": "James Smith",
    "bank_account": "12345678",
    "bsb": "062-000",
    "status": "pending"
  },
  "created_at": "2026-02-18T10:30:00Z"
}

Alternatively, use PayID for faster payouts:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "AUD",
    "method": "payid",
    "type": "withdrawal",
    "merchant_reference": "payout_vendor_001",
    "description": "Payout February 2026",
    "customer": {
      "name": "James Smith",
      "email": "james@example.com",
      "phone": "+61412345678"
    },
    "payout": {
      "recipient_name": "James Smith",
      "payid": "james@example.com",
      "payid_type": "email"
    }
  }'

payout = requests.post(
    "https://api.lux-core.io/api/v1/payments",
    headers={"X-API-Key": "qp_test_sk_your_key_id:your_secret"},
    json={
        "amount": 250000,  # $2,500.00 AUD
        "currency": "AUD",
        "method": "payid",
        "type": "withdrawal",
        "merchant_reference": "payout_vendor_001",
        "description": "Payout February 2026",
        "customer": {
            "name": "James Smith",
            "email": "james@example.com",
            "phone": "+61412345678"
        },
        "payout": {
            "recipient_name": "James Smith",
            "payid": "james@example.com",
            "payid_type": "email"
        }
    }
)

Response (AUD PayID Withdrawal)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "pending",
  "amount": 250000,
  "currency": "AUD",
  "method": "payid",
  "type": "withdrawal",
  "merchant_reference": "payout_vendor_001",
  "payout": {
    "recipient_name": "James Smith",
    "payid": "james@example.com",
    "payid_type": "email",
    "status": "pending"
  },
  "created_at": "2026-02-18T10:30:00Z"
}

PayID Withdrawal Types:

email — recipient’s email registered as PayID (e.g., james@example.com)
phone — recipient’s phone number in E.164 format (e.g., +61412345678)
abn — Australian Business Number (e.g., 51824753556)

Withdrawals require sufficient balance in your merchant account. Use the Balance API to check available funds before initiating payouts.

Per-Payment Webhook URL

You can optionally specify a webhook_url to receive events for a specific payment without pre-configuring a webhook endpoint:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "customer": {
      "name": "Maria Garcia",
      "email": "maria@example.com"
    },
    "webhook_url": "https://your-server.com/webhooks/payments",
    "webhook_events": ["payment.completed", "payment.failed"]
  }'

Field	Type	Required	Description
`webhook_url`	string	No	HTTPS URL to receive webhook events for this payment (max 2048 characters)
`webhook_events`	string[]	No	Events to subscribe to. Defaults to `["payment.created", "payment.completed", "payment.failed", "payment.refunded"]`

In-request webhooks are signed using your merchant’s default webhook secret. See the Webhooks Guide for details on signature verification and secret management.

Traffic Type

Optionally tag payments with a traffic type for analytics and routing:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_123",
    "traffic_type": "primary",
    "customer": {
      "name": "Customer Name",
      "email": "customer@example.com"
    }
  }'

Value	Description
`primary`	Primary traffic (default routing)
`secondary`	Secondary/backup traffic
`vip`	VIP/priority traffic

traffic_type is optional. If not provided, the payment uses default routing. Traffic type is included in payment responses and CSV exports.

Hosted Payment Pages

For a simpler integration, use hosted payment pages (deposit_pp or withdrawal_pp):

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "deposit_pp",
    "merchant_reference": "checkout_123",
    "customer": {
      "name": "Customer Name",
      "email": "customer@example.com"
    }
  }'

Response includes a payment page URL:

{
  "transaction_id": "pay_xyz789",
  "status": "processing",
  "payment_page": {
    "url": "https://{payment-page-host}/pay/{token}?sig={signature}&exp={expires}"
  }
}

The payment page URL is dynamically generated and may vary based on the selected currency, payment method, and region. Always use the exact URL returned in the API response.

Redirect your customer to this URL to complete the payment.

Payment Statuses

Understanding payment statuses is crucial for proper integration. Each status represents a specific state in the payment lifecycle.

Status Reference

Status	Description	Terminal	Webhooks Sent
`created`	Payment accepted, awaiting processing	❌	-
`pending`	Payment created, awaiting processing or approval	❌	-
`processing`	Payment is being processed, awaiting customer action	❌	-
`completed`	Payment was successful, funds transferred	✅	`payment.completed`
`failed`	Payment failed due to error or rejection	✅	`payment.failed`
`cancelled`	Payment was cancelled by merchant or system	✅	`payment.cancelled`
`expired`	Payment expired before completion	✅	`payment.failed`
`refunded`	Payment was fully refunded	✅	`payment.refunded`
`partial_refund`	Payment was partially refunded	✅	`payment.refunded`

Terminal statuses (completed, failed, cancelled, expired, refunded, partial_refund) are final states - the payment cannot transition to non-terminal status.

Initial Status by Payment Type

These are typical nonterminal initial statuses. A creation request can also return a failed payment; always inspect the actual response.

Payment Type	Initial Status	Description
`deposit`	`processing`	Customer needs to complete the transfer
`withdrawal`	`pending`	Awaiting approval and processing
`deposit_pp`	`processing`	Customer redirected to payment page
`withdrawal_pp`	`pending`	Awaiting approval

Status Descriptions

created

The payment has been accepted and is awaiting processing. Check its status or wait for the next notification.Next possible statuses: pending, processing, failed

pending

The payment has been created and is waiting to be processed. For withdrawals, this means the payout is queued and awaiting approval or processing by the payment provider.Next possible statuses: processing, cancelled, expired

processing

The payment is actively being processed. For deposits, this means the customer has been given payment instructions (bank details, payment page URL) and we are waiting for them to complete the transfer.Next possible statuses: completed, failed, cancelled, expired

completed

The payment was successful. For deposits, the funds have been received and credited to your merchant balance. For withdrawals, the funds have been sent to the beneficiary.This is a terminal status. You will receive a payment.completed webhook.

failed

The payment could not be completed. This can happen due to various reasons: bank rejection, invalid account details, insufficient funds (for withdrawals), or technical issues.This is a terminal status. You will receive a payment.failed webhook with an error_code and error_message.

cancelled

The payment was cancelled before completion. Check the final payment status before starting another payment.This is a terminal status. You will receive a payment.cancelled webhook.

expired

The payment was not completed within the allowed time window. Deposits typically expire after 1-60 minutes (configurable per merchant).This is a terminal status. You will receive a payment.failed webhook with error_code: TTL_EXPIRED.

refunded

The payment was fully refunded after completion. The refunded amount has been deducted from your merchant balance.This is a terminal status. You will receive a payment.refunded webhook.

partial_refund

The payment was partially refunded. Part of the original amount has been returned to the customer.This is a terminal status. You will receive a payment.refunded webhook with the refunded amount.

Initiating Refunds

Refunds are currently initiated through the support team. Use the Tickets API to request a refund.

To request a refund:

Create a support ticket with category refund_request via the Tickets API or the merchant dashboard
Include the payment_id of the payment to be refunded
The support team will process the refund and update the payment status
You will receive a payment.refunded webhook when the refund is complete

Refund amounts are deducted from your merchant balance (available_amount decreases). Only completed deposits can be refunded; payouts and payments that are still pending or processing are not eligible.

Handling Status Changes

Use webhooks for payment updates and the status endpoint to reconcile missing or uncertain results. Respect rate limits when polling.

// Example: Handling status in your webhook handler
switch (payment.status) {
  case "completed":
    // Update order to paid, deliver goods/services
    await markOrderAsPaid(payment.merchant_reference);
    break;
  case "failed":
  case "expired":
    // Notify the customer and verify the original outcome before a replacement
    await notifyPaymentFailed(
      payment.merchant_reference,
      payment.error_message,
    );
    break;
  case "cancelled":
    // Clean up pending order
    await cancelOrder(payment.merchant_reference);
    break;
  case "refunded":
  case "partial_refund":
    // Process refund in your system
    await processRefund(payment.merchant_reference, payment.refund);
    break;
}

Retrieving Payment Status

curl -X GET "https://api.lux-core.io/api/v1/payments/pay_1234567890_abcdefgh" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret"

Listing Payments

curl -X GET "https://api.lux-core.io/api/v1/payments?status=completed&limit=20" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret"

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status
`method`	string	Filter by payment method
`created_at_from`	ISO 8601	Start date filter
`created_at_to`	ISO 8601	End date filter
`limit`	integer	Results per page (max 100)
`offset`	integer	Zero-based pagination offset; must be a nonnegative integer

Customer Management

Payments are automatically linked to customers in your account. You can optionally pass an existing customer ID to link a payment to a specific customer.

Customer Fields

Field	Type	Required	Description
`name`	string	No	Customer full name (max 255 characters)
`email`	string	No	Customer email address (max 255 characters)
`phone`	string	No	Customer phone number (max 50 characters)
`document`	string	No	7–20 digits or hyphens; use the required format for your route
`external_id`	string	No	Your unique customer identifier from your system. Used to link payments to your customer records

All customer fields are optional. However, providing at least email or phone is recommended for customer identification and communication.

external_id is your own customer reference (e.g., user ID from your database). Use it to associate payments with your customer records.

Using External ID

Pass external_id inside the customer object to link payments to your customer records:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "customer": {
      "name": "Maria Garcia",
      "email": "maria@example.com",
      "external_id": "usr_98765"
    }
  }'

external_id must be unique per merchant. If you attempt to create a new customer with an external_id that is already assigned to another customer within the same merchant account, the request will fail.

Using Customer ID

If you have an existing customer, you can pass their ID directly:

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "deposit",
    "merchant_reference": "order_abc123",
    "customer_id": 12345,
    "customer": {
      "name": "Maria Garcia",
      "email": "maria@example.com"
    }
  }'

When customer_id is provided, the system validates that the customer exists and belongs to your merchant account. The customer object fields (name, email, phone, external_id) are not updated in this case — only the link to the existing customer is used.

Customer References

Store your own order/customer references together with the returned payment identifier. The create response uses transaction_id; payment lookups use id. Do not require a full customer object in a payment response.

Cancelling a Payment

Cancel a pending payment:

curl -X POST "https://api.lux-core.io/api/v1/payments/pay_1234567890_abcdefgh/cancel" \
  -H "X-API-Key: qp_test_sk_your_key_id:your_secret"

Cancellation can be requested for pending or processing payments. Payouts (withdrawals) can be cancelled only while they are pending and not yet assigned for processing. Cancellation may be rejected when the payment can no longer be safely cancelled; verify the returned status before creating a replacement. An already cancelled payment retains that status.

Idempotency

Use a unique merchant_reference for each order. An existing active reference can return the original payment. References from failed, expired or cancelled payments may be reused; after a timeout or unknown result, check the original outcome before submitting another creation request. Do not assume that reusing a reference makes every retry safe.

Best Practices

Validate Amounts

Always validate amounts before submission. Amounts are in minor units (centavos).

Handle Webhooks

Don’t rely on polling. Set up webhooks for real-time status updates.

Store References

Save transaction_id and merchant_reference for reconciliation.

Check Balance

For withdrawals, verify sufficient balance before initiating.

​Payments Guide

​Response Metadata

​Payment Types

​Payment Methods

​Supported Payment Currencies

​Creating a Deposit (Customer Payment)

​Response (ARS)

​Response (MXN)

​Response (UYU)

​Response (AUD - Bank Transfer)

​Response (AUD - PayID)

​Response (TRY)

​Response (LKR)

​iPay Integration Details

​Checkout Flow

​Response Fields

​Limits

​iPay Callback Statuses

​Fastoo Cross-Border Routes

​Creating a Withdrawal (Payout)

​Payout Fields

​Response (ARS Withdrawal)

​Response (MXN Withdrawal)

​Response (UYU Withdrawal)

​Response (AUD Bank Transfer Withdrawal)

​Response (AUD PayID Withdrawal)

​Per-Payment Webhook URL

​Traffic Type

​Hosted Payment Pages

​Payment Statuses

​Status Reference

​Initial Status by Payment Type

​Status Descriptions

​Initiating Refunds

​Handling Status Changes

​Retrieving Payment Status

​Listing Payments

​Query Parameters

​Customer Management

​Customer Fields

​Using External ID

​Using Customer ID

​Customer References

​Cancelling a Payment

​Idempotency

​Best Practices

Validate Amounts

Handle Webhooks

Store References

Check Balance

Payments Guide

Response Metadata

Payment Types

Payment Methods

Supported Payment Currencies

Creating a Deposit (Customer Payment)

Response (ARS)

Response (MXN)

Response (UYU)

Response (AUD - Bank Transfer)

Response (AUD - PayID)

Response (TRY)

Response (LKR)

iPay Integration Details

Checkout Flow

Response Fields

Limits

iPay Callback Statuses

Fastoo Cross-Border Routes

Creating a Withdrawal (Payout)

Payout Fields

Response (ARS Withdrawal)

Response (MXN Withdrawal)

Response (UYU Withdrawal)

Response (AUD Bank Transfer Withdrawal)

Response (AUD PayID Withdrawal)

Per-Payment Webhook URL

Traffic Type

Hosted Payment Pages

Payment Statuses

Status Reference

Initial Status by Payment Type

Status Descriptions

Initiating Refunds

Handling Status Changes

Retrieving Payment Status

Listing Payments

Query Parameters

Customer Management

Customer Fields

Using External ID

Using Customer ID

Customer References

Cancelling a Payment

Idempotency

Best Practices