Authorization, Capture, Void & Refund

Payment Flows

Moyasar supports two payment flows:

• Purchase (default): Authorizes and captures the payment in one step. The card is charged immediately and the payment status is paid.
• Authorization: Only places a hold on the card without capturing the funds. You then decide whether to capture (charge) or void (release) the held amount.

Purchase Flow

Authorization Flow

---

Authorization

To authorize a payment without charging, set source[manual] to true when creating the payment.

curl -X POST https://api.moyasar.com/v1/payments \
  -u sk_test_YOUR_SECRET_KEY: \
  -d "amount=5000" \
  -d "currency=SAR" \
  -d "description=Order #1234" \
  -d "callback_url=https://example.com/callback" \
  -d "source[type]=creditcard" \
  -d "source[name]=John Doe" \
  -d "source[number]=4111111111111111" \
  -d "source[month]=01" \
  -d "source[year]=2027" \
  -d "source[cvc]=123" \
  -d "source[manual]=true"

The response will have "status": "authorized" instead of "paid".

Important

Authorization holds are set by the card issuer and typically last around 7 days. If you do not capture or void within this period, the hold will eventually expire on its own and the funds will be released back to the cardholder.

---

Capture

Captures an authorized payment, charging the cardholder.

Endpoint: POST /v1/payments/{id}/capture

Authentication: Secret key

Full Capture

curl -X POST https://api.moyasar.com/v1/payments/{payment_id}/capture \
  -u sk_test_YOUR_SECRET_KEY:

Partial Capture

curl -X POST https://api.moyasar.com/v1/payments/{payment_id}/capture \
  -u sk_test_YOUR_SECRET_KEY: \
  -d "amount=3000"

• amount is optional. If omitted, the full authorized amount is captured.
• Capture amount cannot exceed the authorized amount.
• The payment status changes to captured.

---

Void

Releases the hold on an authorized payment, or reverses a paid/captured payment.

Endpoint: POST /v1/payments/{id}/void

Authentication: Secret key

curl -X POST https://api.moyasar.com/v1/payments/{payment_id}/void \
  -u sk_test_YOUR_SECRET_KEY:

No request body is needed. The payment status changes to voided.

tip

Prefer void over refund when possible. Voids release the hold instantly and avoid processing fees.

---

Refund

Returns funds to the cardholder for a charged payment.

Endpoint: POST /v1/payments/{id}/refund

Authentication: Secret key

Full Refund

curl -X POST https://api.moyasar.com/v1/payments/{payment_id}/refund \
  -u sk_test_YOUR_SECRET_KEY:

Partial Refund

curl -X POST https://api.moyasar.com/v1/payments/{payment_id}/refund \
  -u sk_test_YOUR_SECRET_KEY: \
  -d "amount=2000"

• amount is optional. If omitted, the full amount is refunded.
• Refund amount cannot exceed the charged amount.
• For paid payments, the maximum refundable amount is the full amount.
• For captured payments, the maximum refundable amount is the captured amount.
• The payment status changes to refunded.
• For live accounts using aggregation, your account balance must be sufficient to cover the refund.

---

Handling Failures

Capture Failure

1. Check the payment status via GET /v1/payments/{id}.
2. If still authorized, retry the capture once.
3. If it fails again, ask the cardholder to use a different card and create a new payment.

Void Failure

1. Check the payment status via GET /v1/payments/{id}.
2. If still voidable, retry the void once.
3. If it fails again:
   • Authorized payments: No action needed. The hold will expire on its own and the funds will return to the cardholder (typically within 14 days, depending on the issuer).
   • Paid/captured payments: Issue a refund instead.

Refund Failure

1. Check the payment status via GET /v1/payments/{id}.
2. If still paid or captured, retry the refund once.
3. If it fails again, contact Moyasar support with the payment ID.

---

Quick Reference

Operation	Endpoint	Auth	Allowed From Status
Authorize	POST /v1/payments with source[manual]=true	Publishable or Secret key	—
Capture	POST /v1/payments/{id}/capture	Secret key	authorized
Void	POST /v1/payments/{id}/void	Secret key	authorized, paid, captured
Refund	POST /v1/payments/{id}/refund	Secret key	paid, captured