Payments

Create Payment Intent

Create a new payment intent for the hosted checkout page

Creates a new payment intent and returns a redirect URL to the hosted checkout page.

This endpoint is used to create a payment intent for processing payments through the hosted checkout page. A payment intent serves as the foundation for a transaction, specifying details such as the amount and currency required for payment processing.

Hosted Checkout Flow

Once a payment intent is created, you receive a redirect_url to the hosted checkout page. This URL can be used to redirect users to the checkout page, enabling customers to complete the payment process. Our checkout page manages different multi-step flows and 3DS redirection flows, ensuring a smooth user experience.

Request

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token with your API key
`Content-Type`	string	Yes	Must be `application/json`

Body Parameters

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in minor units (cents). E.g., 1000 = $10.00
`currency`	string	Yes	ISO 4217 currency code (e.g., `USD`, `ZAR`, `EUR`)
`reference_id`	string	Yes	Your unique transaction reference
`purchaser_id`	string (min 3 chars)	Yes	Your unique customer identifier
`return_url`	string (HTTPS URI)	Yes	URL to redirect customer after payment
`allow_remember_credentials`	boolean	Yes	Whether payment credentials can be saved
`request_unscheduled_mit`	boolean	No	Request permission for future auto-payments (default: false)
`require_unscheduled_mit`	boolean	No	Require MIT capability (default: false)
`is_interactive`	boolean	No	Whether customer interaction required (default: true)
`capture_mode`	string	No	`immediate` or `prefer_delay` (default: `immediate`)
`purchaser_info`	object	No	Customer details (email, phone, country, locale)
`payment_method_filter`	object	No	Filter which payment methods to show
`split`	object	No	Payment split configuration for multiple beneficiaries

Purchaser Info Object

Field	Type	Required	Description
`email`	string	No	Customer email address
`phone`	string	No	Customer phone number
`country`	string	No	ISO country code (e.g., `ZA`)
`locale`	string	No	Locale code (e.g., `en-ZA`)

Payment Method Filter Object

Field	Type	Required	Description
`filter_type`	string	Yes	`allow` (whitelist) or `block` (blacklist)
`payment_methods`	array	Yes	List of payment method codes

Split Object

Field	Type	Required	Description
`split_type`	string	Yes	Currently only `AMOUNT` supported
`splits`	array (min 2)	Yes	List of beneficiary splits
`description`	string	No	Optional split description

See Split Payouts Guide for details.

The return_url must be a secure HTTPS URL and publicly accessible (not localhost for production).

Currency Decimal Handling: The following currencies do not use 2 decimals:

0 decimals: JPY (Japanese Yen), UGX (Ugandan Shilling)
3 decimals: OMR (Omani Rial), KWD (Kuwaiti Dinar), BHD (Bahraini Dinar), JOD (Jordanian Dinar)

Example Request

curl -X POST https://app.infinic.com/api/intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "ZAR",
    "reference_id": "order_12345",
    "purchaser_id": "customer_abc",
    "return_url": "https://yoursite.com/payment/callback",
    "allow_remember_credentials": true,
    "request_unscheduled_mit": false,
    "purchaser_info": {
      "email": "customer@example.com",
      "phone": "+27123456789",
      "country": "ZA",
      "locale": "en-ZA"
    }
  }'

const response = await fetch("https://app.infinic.com/api/intents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${YOUR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 10000,
    currency: "ZAR",
    reference_id: "order_12345",
    purchaser_id: "customer_abc",
    return_url: "https://yoursite.com/payment/callback",
    allow_remember_credentials: true,
    purchaser_info: {
      email: "customer@example.com",
      phone: "+27123456789",
      country: "ZA",
    },
  }),
});

const data = await response.json();
console.log("Redirect URL:", data.redirect_url);

import requests

response = requests.post(
    'https://app.infinic.com/api/intents',
    headers={
        'Authorization': f'Bearer {YOUR_API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 10000,
        'currency': 'ZAR',
        'reference_id': 'order_12345',
        'purchaser_id': 'customer_abc',
        'return_url': 'https://yoursite.com/payment/callback',
        'allow_remember_credentials': True,
        'purchaser_info': {
            'email': 'customer@example.com',
            'phone': '+27123456789',
            'country': 'ZA'
        }
    }
)

data = response.json()
print('Redirect URL:', data['redirect_url'])

Response

Success Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "redirect_url": "https://app.infinic.com/checkout?intent=550e8400-e29b-41d4-a716-446655440000&token=eyJ0eXAi..."
}

Field	Type	Description
`id`	string (UUID)	Unique payment intent identifier
`token`	string	Intent authentication token (for `iauth` parameter)
`redirect_url`	string	URL to redirect customer to checkout page

Error Responses

401 Unauthorized

{
  "detail": "Invalid or missing API key"
}

Causes:

Missing Authorization header
Invalid API key
Using sandbox key with production URL (or vice versa)

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "ensure this value is greater than or equal to 0",
      "type": "value_error"
    }
  ]
}

Common validation errors:

Negative amount
Invalid currency code
Missing required fields
Invalid return_url format
Split amounts don't sum to total amount

Important Notes

Allow Remember Credentials

The allow_remember_credentials parameter must be set to true if you plan to:

Allow 1-click payments
Enable unscheduled Merchant-Initiated Transactions (MIT)
Use auto-payment attempts

If you intend to use auto-payments, ensure the original payment intent is successfully completed and meets all prerequisites.

See Auto Payments Guide for details.

Split Payouts

If you want to split the payment between multiple parties, use the split field:

Minimum 2 beneficiaries required
Sum of splits must equal total amount
No duplicate beneficiaries
All beneficiaries must have same currency as intent

Before using splits, create beneficiaries using the /api/merchants/{merchant_id}/beneficiaries endpoint.

See Split Payouts Guide for complete details.

Next Steps

After creating a payment intent:

Redirect the customer to the redirect_url
Set up webhook listener to receive payment status updates
Handle return_url callback when customer returns to your site

See the Hosted Checkout Guide for a complete integration walkthrough.

Webhooks

Set up real-time payment notifications with webhooks

Get Payment Intent

Retrieve details and status of a specific payment intent