Payments

Fintech Core wraps the Satim (CIB) gateway so you create a payment with one authenticated call and get back a hosted payment link. All requests use your API key.

Create a payment

curl -X POST http://localhost:8080/api/v1/payments \
  -H "X-API-Key: sk_live_…" -H 'Content-Type: application/json' \
  -d '{
    "amount": "5000.00",
    "order_ref": "INV-1042",
    "success_url": "https://your-app.example/ok",
    "fail_url": "https://your-app.example/ko",
    "description": "Order 1042",
    "language": "FR"
  }'

Field	Required	Notes
`amount`	yes	DZD, minimum `50.00`, at most 2 decimals
`success_url` / `fail_url`	yes	Where the customer is sent after paying
`order_ref`	no	Your reference; echoed in webhooks
`description`	no	Shown on the payment
`language`	no	`AR`, `FR`, or `EN` (default `FR`)

Response:

{ "id": "…", "satim_order_id": "…", "payment_url": "https://test.satim.dz/payment/…" }

Redirect the customer to payment_url.

The return flow

After the customer pays, Satim redirects them to a Fintech Core URL that:

confirms the result with Satim,
updates the payment and enqueues webhooks to your endpoints,
redirects the customer to your success_url (paid) or fail_url (otherwise), appending ?payment_id=…&status=….

You never call Satim directly. To be notified server-side, use webhooks.

Status lifecycle

PENDING → PAID · REFUSED · FAILED · CANCELED · EXPIRED, and PAID → REFUNDED.

curl -H "X-API-Key: sk_live_…" http://localhost:8080/api/v1/payments/PAYMENT_ID

A PENDING payment is refreshed from Satim on read. List with GET /api/v1/payments?status=PAID&limit=50. Once confirmed, the payment also carries the Satim acknowledge fields needed for an IHM-compliant receipt:

Field	Notes
`satim_order_id`	`orderId` from Satim (the transaction id)
`satim_order_number`	`orderNumber` we generated
`approval_code`	authorization number from the Satim authorization server
`resp_code` / `resp_code_desc`	issuer response code and its description (primary message to display)
`action_code_description`	fallback message when `resp_code_desc` is empty
`card_brand`	`CIB` or `EDAHABIA` (derived from the PAN BIN)
`masked_pan`, `paid_at`, `amount`, `currency`	card, timestamp, amount + currency

Refund

Refund a PAID payment (omit the body for a full refund):

curl -X POST http://localhost:8080/api/v1/payments/PAYMENT_ID/refund \
  -H "X-API-Key: sk_live_…" -H 'Content-Type: application/json' \
  -d '{"amount":"1000.00"}'

The payment moves to REFUNDED and a PAYMENT_REFUNDED webhook is sent.

Test cards

Outcome	Card	Exp	CVV2	Password
Valid	`6280581110007215`	01/2027	373	123456
Declined	`6280581110006712`	01/2027	897	123456

Get Started

Concepts

Guides

Reference

Create a payment

The return flow

Status lifecycle

Refund

Test cards

​Create a payment

​The return flow

​Status lifecycle

​Refund

​Test cards

Create a payment

The return flow

Status lifecycle

Refund

Test cards