Quick Start: Card Payment

PCI DSS Required. This integration sends raw card data through your servers, requiring PCI DSS Level 1 compliance. If you can't certify, use the Hosted Payment Page instead. See Choosing Your Integration.

Process a card payment in 3 steps: authenticate, submit payment, handle the response.

#Prerequisites

Sandbox credentials (merchantKey + merchantSecret) from Exirom
A configured callback URL

#Step 1: Authenticate

curl -X POST https://sandbox.api.exirom.com/api/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "merchantKey": "YOUR_MERCHANT_KEY",
    "merchantSecret": "YOUR_MERCHANT_SECRET"
  }'

{
  "merchantKey": "YOUR_MERCHANT_KEY",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Cache this token and reuse it — tokens are valid for 30 days.

#Step 2: Submit a Payment

Note: Card API uses mid (Merchant ID) while APM API uses accountId to identify your merchant account. Both values are provided by Exirom during onboarding -- they are different identifiers for the same merchant.

curl -X POST https://sandbox.api.exirom.com/api/api/v1/payments/card \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "requestId": "unique-request-id-001",
    "mid": "YOUR_MID",
    "amount": "10.00",
    "currency": "USD",
    "lang": "en",
    "card": {
      "number": "4111111111111111",
      "expMonth": "12",
      "expYear": "2028",
      "cvv": "123",
      "cardHolderName": "Test User",
      "requestThreeDSecure": true
    },
    "billingDetails": {
      "externalUserId": "user-001",
      "firstName": "Test",
      "lastName": "User",
      "email": "test@example.com",
      "phone": "+15551234567",
      "address1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "postalCode": "10001",
      "dateOfBirth": "1990-01-01"
    },
    "order": {
      "orderId": "order-001",
      "title": "Test Purchase"
    },
    "callbackUrl": "https://your-domain.com/callback",
    "successRedirectUrl": "https://your-domain.com/success",
    "failureRedirectUrl": "https://your-domain.com/failure",
    "device": {
      "ip": "203.0.113.1",
      "userAgent": "Mozilla/5.0"
    }
  }'

{
  "transactionId": "txn_abc123",
  "transactionStatus": "NEW",
  "challengeUrl": null
}

Note: Initial status NEW means the transaction is accepted and processing has begun. Do not treat this as a final result -- wait for the webhook callback for the authoritative outcome.

Note: Setting requestThreeDSecure: true requests 3D Secure authentication. The issuer's risk engine decides whether to present a challenge — even with false, the issuer may still require 3DS. See 3D Secure Auth Flow for details.

If challengeUrl is returned, redirect the customer there for 3D Secure verification.

For full request/response schema, see POST /api/v1/payments/card API Reference.

#Step 3: Receive the Result

Exirom sends a webhook POST to your callbackUrl when the transaction reaches a terminal status.

{
  "transactionId": "txn_abc123",
  "transactionStatus": "SUCCEED",
  "amount": 10.00,
  "currency": "USD",
  "requestId": "unique-request-id-001"
}

Verify the callback signature using HMAC-SHA256 and return HTTP 200 immediately.

#Sandbox Test Cards

Card Number	Scenario
`4111111111111111`	Approved
`4000000000000002`	Declined
`4000000000003220`	3DS Challenge

#What's Next?

Full Card Payment Guide — all request/response fields
3D Secure Flow — handling 3DS redirects
Tokenize & Charge — save cards for repeat customers
Webhooks — callback setup and verification
Integration Checklist — pre-go-live checklist