Skip to main content

Standalone Authentication

A standalone authentication (card_auth) is a 3D Secure authentication on its own — it has an amount, a currency, and a card, but it does not charge anything. Use it to authenticate now and charge later, or to authenticate on Moyasar and authorize elsewhere.

Full request/response details are in the Card Authentication API reference; this page walks through the flow.

warning

Standalone 3D Secure is enabled only for selected merchants.

Only use this flow if you want to bring 3DS values from another provider, or you want to separate the 3DS steps from the payment. If you don't, don't call /v1/card_auths — follow 3DS in a Payment instead, where Moyasar runs 3DS for you.

1. Create the authentication​

Endpoint: POST /v1/card_auths

Authentication: Publishable key

POST /v1/card_auths
{
  "amount": 10000,
  "currency": "SAR",
  "callback_url": "https://merchant.example/3ds/return",
  "source": {
    "type": "creditcard",
    "name": "John Doe",
    "number": "4111111111111111",
    "month": "12",
    "year": "2030",
    "cvc": "123"
  }
}

When a challenge is needed, the response is available with a transaction_url:

{
  "id": "ca_2a1b...",
  "status": "available",
  "amount": 10000,
  "currency": "SAR",
  "transaction_url": "https://api.moyasar.com/v1/card_auth/ca_2a1b.../prepare",
  "callback_url": "https://merchant.example/3ds/return",
  "card": { "company": "visa", "last_digits": "1111" },
  "result": null,
  "created_at": "2026-05-20T10:00:00Z"
}

If the card isn't enrolled, the status comes back failed with no transaction_url.

2. Send the cardholder through the challenge​

Redirect the cardholder to transaction_url. The in-browser flow is the same one used by payments; frictionless authentications complete without a visible challenge. Afterwards the cardholder is returned to your callback_url.

3. Read the result​

Fetch the authentication. Once the cardholder finishes, status is authenticated or failed and result is populated.

Endpoint: GET /v1/card_auths/{id}

Authentication: Secret key

The result object is only returned with secret key authentication. A publishable key may fetch the authentication for 15 minutes after creation — for example to check the status after the redirect — but result is always null on those responses.

{
  "id": "ca_2a1b...",
  "status": "authenticated",
  "result": {
    "eci": "05",
    "authentication_value": "AAICCGhVkQAAACcQaCFSdYh0YUg=",
    "ds_transaction_id": "f8c3a0d2-7e76-4df1-8ba4-f457386d14bf",
    "version": "2.2.0",
    "transaction_status": "Y",
    "auth_scheme": "visa",
    "acs_transaction_id": "002cef25-c015-4f95-bfd5-220138133161",
    "ds_reference_number": "VISA.V 17 0003",
    "acs_reference_number": "3DS_LOA_ACS_MOMD_020301_00793",
    "three_ds_server_transaction_id": "f0d50f2f-86c4-47aa-a4e3-c81547c1f8fa",
    "is_frictionless": false,
    "message": null
  }
}

See the API reference for every field.

Webhook​

A webhook fires when the authentication reaches a terminal state: card_auth_authenticated on success and card_auth_failed when it fails or expires. The payload matches the fetch response. Both events are only available once standalone authentication is enabled for your account — until then they do not appear in the webhook event list and cannot be subscribed to. See Setting up webhooks.

Next: use it in a payment​

Once authenticated, charge the card by referencing the authentication — see Use an authentication in a payment.

Last updated on