Payments Flow

Creating a payment does not start collection; confirm is required to capture funds. SDK examples reflect the REST model; for detailed lifecycle see Payment Lifecycle and Confirm.

Create payment

const payment = await hsrcpay.payments.create({
  amount: 15900,
  currency: "TRY",
  autoCapture: true,
  secureMode: true,
  metadata: { cartId: "CART-1042" },
});
// payment.status is usually CREATED

Confirm

const result = await hsrcpay.payments.confirm(payment.id, {
  paymentMethod: { id: "pm_xxx" },
  payerIdentity: {
    ipAddress: clientIp,
    userAgent: request.headers.get("user-agent") ?? "",
  },
});

if (result.payment.status === "REQUIRES_ACTION" && result.confirmResult.paymentNextAction?.url) {
  redirect(result.confirmResult.paymentNextAction.url);
}

The confirm response includes both the updated payment and confirmResult (orchestrator summary); do not decide order state from payment.status alone, reconcile with webhooks.

Statuses (API)

Status	Short meaning
`CREATED`	Record opened, awaiting confirm
`REQUIRES_PAYMENT_METHOD`	No method or last attempt failed
`REQUIRES_ACTION`	3DS / redirect
`AUTHORIZED`	Auth-only success
`SUCCEEDED`	Collection completed
`CANCELED` / `REFUNDED` / `EXPIRED`	Terminal or refund

Decline detail is usually on the charge record (DECLINED); on the payment side you may plan another confirm.

Application-side state map

Do not lock your order state 1

to the API enum; use a domain layer in between such as pending, awaiting_3ds, paid.

Errors

4xx: payload, authorization, or business rule
409: idempotency conflict (write operations)
5xx: transient; limited retry with the same idempotency key, then payment GET