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"
  }'
FieldRequiredNotes
amountyesDZD, minimum 50.00, at most 2 decimals
success_url / fail_urlyesWhere the customer is sent after paying
order_refnoYour reference; echoed in webhooks
descriptionnoShown on the payment
languagenoAR, 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:
  1. confirms the result with Satim,
  2. updates the payment and enqueues webhooks to your endpoints,
  3. 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:
FieldNotes
satim_order_idorderId from Satim (the transaction id)
satim_order_numberorderNumber we generated
approval_codeauthorization number from the Satim authorization server
resp_code / resp_code_descissuer response code and its description (primary message to display)
action_code_descriptionfallback message when resp_code_desc is empty
card_brandCIB or EDAHABIA (derived from the PAN BIN)
masked_pan, paid_at, amount, currencycard, 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

OutcomeCardExpCVV2Password
Valid628058111000721501/2027373123456
Declined628058111000671201/2027897123456