Create an Operation

Overview

Operations are the core of the 88Pay API. An operation can be a payment charge (PAYIN), a cashout (PAYOUT), or any other transaction type. This guide covers how to create and manage operations.

Prerequisites: You must have a valid authentication token before creating operations.

Operation Types

88Pay supports two main operation flows:

PAYIN - Receive Money
PAYOUT - Send Money

Purpose: Accept payments from customersCommon Use Cases:

E-commerce checkouts
Service payments
Subscription billing
Invoice payments

Available Methods:

Credit/Debit Cards
Cash payments (vouchers)
Bank transfers
Digital wallets (Nequi, Daviplata, etc.)
Cryptocurrencies (USDT)

See all payment methods →

Create a Payment Charge (PAYIN)

Endpoint

POST https://api-sandbox.88pay.io/api/transactions/charges

Required Headers

Authorization: Bearer {access_token}
x-session-id: {session_id}
Content-Type: application/json

Request Parameters

flow

string

required

Operation flow type. Use "PAYIN" for receiving payments

method_code

string

required

Payment method codeExamples: "CARDS", "NEQUI", "CASH", "BANK_TRANSFER", "USDT"See all method codes →

method_category

string

required

Payment method categoryOptions: "CARD", "WALLET", "CASH", "BANK", "CRYPTO"

amount

number

required

Transaction amount. Decimal values allowedExample: 50000 or 50000.50

currency

string

required

ISO 4217 currency codeExamples: "COP", "USD", "MXN", "BRL"

country

string

required

ISO 3166-1 alpha-3 country codeExamples: "COL", "MEX", "BRA", "CHL"

description

string

required

Transaction description visible to the customerExample: "Order #12345 - Black T-Shirt"

customer_id

string

required

Unique identifier for the customer in your systemExample: "user_abc123" or "cust_001"

notification_url

string

required

Your webhook endpoint URL to receive transaction updatesExample: "https://yoursite.com/webhooks/88pay"Learn about webhooks →

return_url

string

URL where the customer returns after completing payment (required for redirect-based methods like cards)Example: "https://yoursite.com/payment/success"

Example Requests

Success Response

{
  "status": "Success",
  "code": 200,
  "message": "Method processed",
  "data": {
    "urlCheckout": "https://link.88pay.io/GSW4WAR",
    "reference": "IP9BD7CJES6",
    "customer_id": "user_abc123",
    "currency": "COP",
    "amount": 50000
  }
}

Response Fields

urlCheckout

string

Checkout page URL where you should redirect the customer to complete paymentNote: Only present for redirect-based methods (cards, some wallets)

reference

string

Unique 88Pay reference for this transaction. Use this to track the payment

customer_id

string

The customer ID you provided in the request

currency

string

Transaction currency

amount

number

Transaction amount

Different Payment Methods

Cards
Cash
Bank Transfer
Digital Wallets
Crypto (USDT)

Credit/Debit Card Payments

    {
      "flow": "PAYIN",
      "method_code": "CARDS",
      "method_category": "CARD",
      "amount": 50000,
      "currency": "COP",
      "country": "COL",
      "description": "Purchase #123",
      "customer_id": "cust_001",
      "notification_url": "https://yoursite.com/webhook",
      "return_url": "https://yoursite.com/success"
    }

Customer Flow:

Redirect to urlCheckout
Customer enters card details
Customer completes 3D Secure if required
Returns to return_url
Webhook sent with final status

Learn more about card payments →

Cash Payments (Vouchers)

    {
      "flow": "PAYIN",
      "method_code": "CASH",
      "method_category": "CASH",
      "amount": 50000,
      "currency": "COP",
      "country": "COL",
      "description": "Purchase #123",
      "customer_id": "cust_001",
      "notification_url": "https://yoursite.com/webhook"
    }

Customer Flow:

Receive payment voucher with barcode/reference
Visit authorized collection point
Pay cash
Webhook sent when payment confirmed

Learn more about cash payments →

Bank Transfer Payments

    {
      "flow": "PAYIN",
      "method_code": "BANK_TRANSFER",
      "method_category": "BANK",
      "amount": 50000,
      "currency": "COP",
      "country": "COL",
      "description": "Purchase #123",
      "customer_id": "cust_001",
      "notification_url": "https://yoursite.com/webhook"
    }

Customer Flow:

Receive bank account details
Make transfer from their bank
Webhook sent when transfer detected

Learn more about bank transfers →

Digital Wallet Payments (Nequi, Daviplata, etc.)

    {
      "flow": "PAYIN",
      "method_code": "NEQUI",
      "method_category": "WALLET",
      "amount": 50000,
      "currency": "COP",
      "country": "COL",
      "description": "Purchase #123",
      "customer_id": "cust_001",
      "notification_url": "https://yoursite.com/webhook",
      "return_url": "https://yoursite.com/success"
    }

Available Wallets (Colombia):

NEQUI - Nequi
DAVIPLATA - Daviplata
PAYPAL - PayPal

Learn more about digital wallets →

Cryptocurrency Payments

    {
      "flow": "PAYIN",
      "method_code": "USDT",
      "method_category": "CRYPTO",
      "amount": 50,
      "currency": "USD",
      "country": "COL",
      "description": "Purchase #123",
      "customer_id": "cust_001",
      "notification_url": "https://yoursite.com/webhook",
      "return_url": "https://yoursite.com/success"
    }

Note: Amount should be in the cryptocurrency denominationLearn more about crypto payments →

Create a Cashout (PAYOUT)

Endpoint

POST https://api-sandbox.88pay.io/api/transactions/cashout-bank-transfer

Bank Transfer Payout Example

curl -X POST "https://api-sandbox.88pay.io/api/transactions/cashout-bank-transfer" \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..." \
  -H "x-session-id: sess_53a2cfc4-441e-4554-b560-4e008784d98e" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "PAYOUT",
    "method_code": "BANK_TRANSFER",
    "method_category": "BANK",
    "amount": 100000,
    "currency": "COP",
    "country": "COL",
    "description": "Vendor payment #789",
    "customer_id": "vendor_xyz",
    "notification_url": "https://yoursite.com/webhooks/88pay",
    "bank_account": {
      "account_number": "1234567890",
      "account_type": "savings",
      "bank_code": "001",
      "holder_name": "Juan Perez",
      "holder_document": "1234567890",
      "holder_document_type": "CC"
    }
  }'

Additional Payout Parameters

bank_account.account_number

string

required

Recipient’s bank account number

bank_account.account_type

string

required

Account type: "savings" or "checking"

bank_account.bank_code

string

required

Bank identifier code. See bank codes by country →

bank_account.holder_name

string

required

Full name of the account holder

bank_account.holder_document

string

required

Account holder’s document number

bank_account.holder_document_type

string

required

Document type: "CC" (Cédula), "NIT", "CE", "PP", etc.

Complete Integration Example

Here’s a full example from token generation to payment creation:

// Complete payment flow
async function processPayment() {
  try {
    // Step 1: Generate token
    const tokenResponse = await fetch('https://api-sandbox.88pay.io/api/auth/token', {
      method: 'POST',
      headers: {
        'x-api-key': process.env.EIGHTY_EIGHT_PAY_API_KEY,
        'x-merchant-id': process.env.EIGHTY_EIGHT_PAY_MERCHANT_ID
      }
    });
    
    const tokenData = await tokenResponse.json();
    const { access_token, session_id } = tokenData.data;
    
    // Step 2: Create payment
    const paymentResponse = await fetch('https://api-sandbox.88pay.io/api/transactions/charges', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${access_token}`,
        'x-session-id': session_id,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        flow: "PAYIN",
        method_code: "CARDS",
        method_category: "CARD",
        amount: 50000,
        currency: "COP",
        country: "COL",
        description: "Test Purchase",
        customer_id: "user_123",
        notification_url: "https://yoursite.com/webhook",
        return_url: "https://yoursite.com/success"
      })
    });
    
    const payment = await paymentResponse.json();
    
    // Step 3: Redirect customer
    if (payment.status === "Success" && payment.data.urlCheckout) {
      window.location.href = payment.data.urlCheckout;
    }
    
    return payment;
    
  } catch (error) {
    console.error('Payment processing failed:', error);
    throw error;
  }
}

Transaction Lifecycle

Error Responses

400 Bad Request

    {
      "status": "Error",
      "code": 400,
      "message": "Invalid request parameters",
      "errors": {
        "amount": "Amount must be greater than 0",
        "currency": "Invalid currency code"
      }
    }

Common Causes:

Missing required fields
Invalid parameter values
Incorrect data types

Solution: Validate all parameters before sending

401 Unauthorized

    {
      "status": "Error",
      "code": 401,
      "message": "Invalid or expired token"
    }

Cause: Token expired or invalidSolution: Generate a new token

422 Unprocessable Entity

    {
      "status": "Error",
      "code": 422,
      "message": "Payment method not available for this country"
    }

Common Causes:

Payment method not supported in specified country
Currency not supported
Amount outside allowed range

Solution: Check available methods for your country

Best Practices

Idempotency

Store the reference returned by 88Pay to avoid duplicate charges

Webhooks

Always implement webhooks - never rely solely on return_url for payment confirmation

Error Handling

Gracefully handle all possible error responses

Test Thoroughly

Test all payment flows in sandbox before going live

Next Steps

Set Up Webhooks

Receive real-time payment notifications

Payment Methods

Explore all available payment methods

Check Balance

Monitor your merchant balance

API Reference

Full technical reference

Core Integration

Advanced

Overview

Operation Types

Create a Payment Charge (PAYIN)

Endpoint

Required Headers

Request Parameters

Example Requests

Success Response

Response Fields

Different Payment Methods

Credit/Debit Card Payments

Cash Payments (Vouchers)

Bank Transfer Payments

Digital Wallet Payments (Nequi, Daviplata, etc.)

Cryptocurrency Payments

Create a Cashout (PAYOUT)

Endpoint

Bank Transfer Payout Example

Additional Payout Parameters

Complete Integration Example

Transaction Lifecycle

Error Responses

Best Practices

Idempotency

Webhooks

Error Handling

Test Thoroughly

Next Steps

Set Up Webhooks

Payment Methods

Check Balance

API Reference

Core Integration

Advanced

​Overview

​Operation Types

​Create a Payment Charge (PAYIN)

​Endpoint

​Required Headers

​Request Parameters

​Example Requests

​Success Response

​Response Fields

​Different Payment Methods

​Credit/Debit Card Payments

​Cash Payments (Vouchers)

​Bank Transfer Payments

​Digital Wallet Payments (Nequi, Daviplata, etc.)

​Cryptocurrency Payments

​Create a Cashout (PAYOUT)

​Endpoint

​Bank Transfer Payout Example

​Additional Payout Parameters

​Complete Integration Example

​Transaction Lifecycle

​Error Responses

​Best Practices

Idempotency

Webhooks

Error Handling

Test Thoroughly

​Next Steps

Set Up Webhooks

Payment Methods

Check Balance

API Reference

Overview

Operation Types

Create a Payment Charge (PAYIN)

Endpoint

Required Headers

Request Parameters

Example Requests

Success Response

Response Fields

Different Payment Methods

Credit/Debit Card Payments

Cash Payments (Vouchers)

Bank Transfer Payments

Digital Wallet Payments (Nequi, Daviplata, etc.)

Cryptocurrency Payments

Create a Cashout (PAYOUT)

Endpoint

Bank Transfer Payout Example

Additional Payout Parameters

Complete Integration Example

Transaction Lifecycle

Error Responses

Best Practices

Next Steps