Payments Guide

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

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

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

Creating a Deposit (Customer Payment)

When a customer needs to pay you:

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

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_your_key" \
  -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"
    }
  }'

Response (ARS)

{
  "transaction_id": "pay_1234567890_abcdefgh",
  "status": "processing",
  "amount": 150000,
  "currency": "ARS",
  "method": "bank_transfer",
  "type": "deposit",
  "instructions": {
    "bank_name": "Banco Nacion",
    "cbu": "0110012345678901234567",
    "alias": "LUXCORE.PAGOS",
    "beneficiary": "LuxCore Platform S.A."
  },
  "created_at": "2025-01-21T10:30:00Z"
}

Creating a Withdrawal (Payout)

To send money to a beneficiary:

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

curl -X POST "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "ARS",
    "method": "bank_transfer",
    "type": "withdrawal",
    "merchant_reference": "payout_vendor_001",
    "description": "Vendor payment January 2025",
    "customer": {
      "name": "Vendor Payments",
      "email": "finance@yourcompany.com"
    },
    "payout": {
      "recipient_name": "Juan Perez Martinez",
      "bank_account": "0110012345678901234567",
      "reference": "PAYOUT-JAN-001"
    }
  }'

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"
}

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

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_your_key" \
  -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
`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

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

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. This can be initiated by the merchant via API, by an admin, or automatically by the system.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: 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.

Handling Status Changes

Always use webhooks to track payment status changes. Polling the API is not recommended as it adds latency and may hit rate limits.

// 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 customer, allow retry
    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.refunded_amount);
    break;
}

Retrieving Payment Status

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

Listing Payments

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

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	Pagination offset

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_your_key"

Only payments in pending or created status can be cancelled.

Idempotency

Use unique merchant_reference values for idempotency. If you submit a payment with a reference that was already used, the API will return the existing payment instead of creating a duplicate.

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.

Getting Started

Guides

SDKs & Examples

Reference

Payments Guide

Payments Guide

Payment Types

Payment Methods

Creating a Deposit (Customer Payment)

Response (ARS)

Creating a Withdrawal (Payout)

Response (ARS Withdrawal)

Hosted Payment Pages

Payment Statuses

Status Reference

Initial Status by Payment Type

Status Descriptions

Handling Status Changes

Retrieving Payment Status

Listing Payments

Query Parameters

Cancelling a Payment

Idempotency

Best Practices

Validate Amounts

Handle Webhooks

Store References

Check Balance

Getting Started

Guides

SDKs & Examples

Reference

​Payments Guide

​Payment Types

​Payment Methods

​Creating a Deposit (Customer Payment)

​Response (ARS)

​Creating a Withdrawal (Payout)

​Response (ARS Withdrawal)

​Hosted Payment Pages

​Payment Statuses

​Status Reference

​Initial Status by Payment Type

​Status Descriptions

​Handling Status Changes

​Retrieving Payment Status

​Listing Payments

​Query Parameters

​Cancelling a Payment

​Idempotency

​Best Practices

Validate Amounts

Handle Webhooks

Store References

Check Balance

Payments Guide

Payment Types

Payment Methods

Creating a Deposit (Customer Payment)

Response (ARS)

Creating a Withdrawal (Payout)

Response (ARS Withdrawal)

Hosted Payment Pages

Payment Statuses

Status Reference

Initial Status by Payment Type

Status Descriptions

Handling Status Changes

Retrieving Payment Status

Listing Payments

Query Parameters

Cancelling a Payment

Idempotency

Best Practices