Guide

Accept an online payment

This is the card-not-present (online) flow — the supported path today. You collect payment details in the browser, tokenize them, and charge server-side with a single API call.

Your merchant must be onboarded and approved before charges succeed. If they aren't, POST /v1/payments returns a 403 merchant-not-ready. See Onboarding & readiness.

1. Tokenize the buyer with Finix.js

On your checkout page, use Finix.js to collect the buyer's card or bank account. Raw details go straight to Finix and never touch your server. Tokenizing returns one of:

  • finixToken — a single-use token for a one-off charge.
  • finixInstrumentId — a stored payment instrument you can reuse.

Pass whichever you have to the charge call below.

2. Create the payment

Call POST /v1/payments with the amount and the token or instrument id. orderRef is your own reference for the order. 

curl https://connect.pay-pi.com/v1/payments \
  -H "X-Api-Key: lc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 4200,
    "currency": "USD",
    "finixToken": "TKe9xh2...",
    "orderRef": "order-1042"
  }'

Request fields

amountCentsInteger, minor units (e.g. 4200 = $42.00).
currencyISO 4217 code, e.g. USD.
finixTokenSingle-use token from Finix.js. Provide this or finixInstrumentId.
finixInstrumentIdReusable stored instrument. Provide this or finixToken.
orderRefYour order reference, echoed back and included on webhooks.

Response

A successful card charge settles synchronously:

{
  "lcPaymentId": "pay_9Qk3...",
  "status": "SUCCEEDED",
  "applicationFeeCents": 135,
  "finixTransferId": "TR8mZ...",
  "finixState": "SUCCEEDED"
}
lcPaymentIdPay-Pi's id for the payment — use it for lookups and refunds.
statusPay-Pi status: SUCCEEDED, PENDING, FAILED, or REFUNDED.
applicationFeeCentsThe Pay-Pi fee applied to this payment.
finixTransferIdThe underlying Finix transfer id.
finixStateThe raw Finix transfer state.

Card vs. ACH settlement

Card payments return a final SUCCEEDED (or FAILED) status in the response. ACH payments are asynchronous — the charge is accepted as PENDING and settles later. You'll receive a webhook when it settles or fails. 

{
  "lcPaymentId": "pay_2Bd7...",
  "status": "PENDING",
  "applicationFeeCents": 100,
  "finixTransferId": "TRa1Q...",
  "finixState": "PENDING"
}

Look up a payment

Fetch the current state of a payment at any time:

curl https://connect.pay-pi.com/v1/payments/pay_9Qk3... \
  -H "X-Api-Key: lc_live_..."

Returns the same payment shape shown above, reflecting the latest status.

Refund a payment

Reverse a payment with POST /v1/payments/{id}/refund. The response is the updated payment with a REFUNDED status. 

curl -X POST https://connect.pay-pi.com/v1/payments/pay_9Qk3.../refund \
  -H "X-Api-Key: lc_live_..."
{
  "lcPaymentId": "pay_9Qk3...",
  "status": "REFUNDED",
  "applicationFeeCents": 135,
  "finixTransferId": "TR8mZ...",
  "finixState": "SUCCEEDED"
}

Errors

Failed requests return RFC 7807 problem+json. Common cases: a merchant that isn't ready and provider (Finix) errors such as declines. See the full error reference.