Payments

Paylinker's core API revolves around the Payment object. This guide explains how to process payments, handle different payment states, and manage payment lifecycles securely and efficiently.

Payment Lifecycle

A payment goes through several states from creation to completion. Understanding these states is crucial for building a robust integration.

State	Description
pending	The payment intent has been created but not yet processed.
processing	The payment is currently being processed by the card network or bank.
succeeded	The payment was successfully captured.
failed	The payment attempt failed (e.g., insufficient funds, declined).
canceled	The payment was canceled before it could be processed.

Creating a Payment

To accept a payment, you first create a PaymentIntent. This object tracks the lifecycle of the transaction.

Request Example

curl https://api.paylinker.com/v1/payments \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d amount=2000 \
  -d currency=usd \
  -d "payment_method_types[]"=card

Response Example

View JSON Response

{
  "id": "pi_1F7XJPCjWp3Z",
  "object": "payment",
  "amount": 2000,
  "currency": "usd",
  "status": "pending",
  "client_secret": "pi_1F7XJPCjWp3Z_secret_8W7..."
}

Handling Payment Results

Since payments can happen asynchronously (e.g., 3D Secure authentication, bank transfers), you should not rely solely on the API response.

Listen to Webhooks

Always listen to webhooks to confirm the final status of a payment.

• payment.succeeded: Fulfill the order.
• payment.failed: Notify the customer and ask for a new payment method.

Best Practices

Idempotency

Always use Idempotency-Key headers to prevent duplicate charges during network retries.

Error Handling

Gracefully handle decline codes (e.g., insufficient_funds) by prompting the user to try a different card.