Accepting Payments (PAYIN)

Learn how to accept payments from customers using local payment methods across Latin America.

What is PAYIN?

PAYIN is the order type used to accept payments from customers into your virtual balance account.

Use Cases

How It Works

High-Level Flow

1. 1

   Customer initiates checkout

   User adds items to cart and proceeds to payment

2. 2

   Your app creates PAYIN order

   Send order details to Koywe API

3. 3

   Koywe returns payment URL

   Receive a checkout URL for the customer

4. 4

   Customer completes payment

   Customer is redirected to payment page and pays using their preferred method

5. 5

   Koywe confirms payment

   Payment provider confirms and Koywe credits your virtual account

6. 6

   Your app receives webhook

   You’re notified via webhook to fulfill the order

Detailed Flow Diagram

Supported Countries and Payment Methods

Colombia 🇨🇴

Learn more about Colombian payment methods →

Brazil 🇧🇷

Mexico 🇲🇽

Chile 🇨🇱

Argentina 🇦🇷

Prerequisites

Before integrating PAYIN orders, ensure you have:

Quick Start

Want to jump right in? Follow our step-by-step integration guide:

Or try the quickstart for a faster overview:

Payment Flow Explained

Step-by-Step Process

1. Authentication

Obtain an access token using your API credentials.

const token = await authenticate(apiKey, secret);

2. Get Available Payment Methods

Query which payment methods are available for the customer’s country.

const methods = await getPaymentMethods('CO', 'COP');
// Returns: PSE, NEQUI, etc.

3. Create Contact (Optional but Recommended)

Store customer information for tracking and compliance.

const contact = await createContact({
  firstName: 'Juan',
  lastName: 'Pérez',
  countrySymbol: 'CO',
  businessType: 'PERSON',
  type: 'PERSON',
  email: 'customer@example.com'
});

4. Create PAYIN Order

Create the payment order with amount and payment method.

const order = await createPayinOrder({
  amount: 50000,
  currency: 'COP',
  paymentMethod: 'PSE',
  contactId: contact.id
});

5. Redirect Customer

Send customer to the payment URL to complete payment.

window.location.href = order.providedAction;

6. Handle Webhooks

Listen for webhook events to know when payment is complete.

// Webhook: order.completed
// -> Fulfill order, send confirmation email

Order Status Progression

Understanding order statuses:

Key Concepts

Payment URL

Every PAYIN order returns a providedAction:

{
  "providedAction": "https://checkout.koywe.com/pay/ord_abc123"
}

This URL:

• Is hosted by Koywe
• Provides a secure payment experience
• Handles the payment method UI
• Redirects back to your successUrl or failedUrl

Success and Failed URLs

Specify where to redirect customers after payment:

{
  "successUrl": "https://yoursite.com/payment/success",
  "failedUrl": "https://yoursite.com/payment/failed"
}

External ID (Idempotency)

Use externalId to link orders to your system and prevent duplicates:

{
  "externalId": "order-12345"  // Your internal order ID
}

Benefits:

• Safe to retry failed API calls
• Prevents duplicate charges
• Easy reconciliation with your database

Common Integration Patterns

Pattern 1: Simple Checkout

// 1. User clicks "Pay"
// 2. Create order
const order = await createPayinOrder({
  amount: cartTotal,
  currency: 'COP',
  paymentMethod: 'PSE'
});
// 3. Redirect
window.location.href = order.providedAction;
// 4. Handle webhook
// 5. Fulfill order

Pattern 2: Payment Method Selection

// 1. Show available methods
const methods = await getPaymentMethods(country, currency);
// 2. User selects method
// 3. Create order with selected method
const order = await createPayinOrder({
  amount: cartTotal,
  currency: 'COP',
  paymentMethod: userSelectedMethod
});
// 4. Redirect and handle webhook

Pattern 3: Stored Customer

// 1. Check if customer exists
let contact = await findContact(email);
if (!contact) {
  contact = await createContact(customerData);
}
// 2. Create order linked to contact
const order = await createPayinOrder({
  amount: cartTotal,
  contactId: contact.id,
  // ... other fields
});
// 3. Track payment history per contact

Next Steps

Additional Resources

• Core Concepts - Orders
• Webhooks Deep Dive
• Error Handling
• API Reference