Payments Gateway Service Overview^beta

Card Present

Endpoint: POST /v1/transactions/card-present

When to use:

• Physical terminal/POS transactions
• Card is physically present and inserted/tapped
• EMV chip card transactions
• Contactless payments

Example Scenario:
Processing a €25 card present transaction at a retail terminal:

# Process card present transaction
curl -X POST "https://base-url.salt/api/v1/transactions/card-present" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: terminal-txn-12345" \
  -d '{
    "type": "SALE",
    "entry_mode": "CONTACT_EMV",
    "verification_method": "ONLINE_PIN",
    "amounts": {
      "amount": 2500,
      "currency": "EUR"
    },
    "terminal_id": "12345678",
    "emv_data": "5F2A020978820200009F3602...",
    "track_data": {
      "encryption_key_id": "5EE0",
      "encrypted_track": "5188340000000011D241212099999999",
      "encryption_ksn": "123456789012"
    },
    "transacted_at": "2024-01-15T10:30:00.000Z"
  }'

Pre-auth & Capture

Endpoints: POST /v1/transactions/card-present (with PRE_AUTHORISATION type) → POST /v1/transactions/{id}/capture

When to use:

• Hotel, car rental, or reservation scenarios with physical card
• Need to reserve funds before actual charge
• Variable final amount (e.g., with tips or additional services)
• Card is physically present for pre-authorization

Example Scenario:
Hotel reservation with €100 pre-auth at check-in, later captured for €85 at checkout:

# Step 1: Create pre-authorization at hotel front desk
curl -X POST "https://base-url.salt/api/v1/transactions/card-present" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hotel-preauth-12345" \
  -d '{
    "type": "PRE_AUTHORISATION",
    "entry_mode": "CONTACT_EMV",
    "verification_method": "ONLINE_PIN",
    "amounts": {
      "amount": 10000,
      "currency": "EUR"
    },
    "terminal_id": "12345678",
    "emv_data": "5F2A020978820200009F3602...",
    "track_data": {
      "encryption_key_id": "5EE0",
      "encrypted_track": "5188340000000011D241212099999999",
      "encryption_ksn": "123456789012"
    },
    "transacted_at": "2024-01-15T14:00:00.000Z"
  }'

# Step 2: Capture with final amount at checkout
curl -X POST "https://base-url.salt/api/v1/transactions/tr_12345/capture" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hotel-capture-12345" \
  -d '{
    "amount": 8500,
    "terminal_id": "12345678"
  }'

Manual Entry

Endpoint: POST /v1/transactions/moto

When to use:

• Card is not physically present
• Merchant manually enters the card details via a virtual terminal
• Mail order or telephone order (MOTO) transactions
• Phone reservations, call-center orders, mail-in orders

Card data format:
encrypted_card_data is the hex-encoded ciphertext of the plaintext string PAN=YYMM=CVV2, F-padded to a multiple of 8 bytes before encryption.

Example Scenario:
Processing a €45 phone order where the customer reads their card details to the merchant:

# Process manual entry transaction
curl -X POST "https://base-url.salt/api/v1/transactions/moto" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: manual-entry-txn-12345" \
  -d '{
    "type": "SALE",
    "terminal_id": "12345678",
    "merchant_reference": "phone-order-7789",
    "amounts": {
      "amount": 4500,
      "currency": "EUR"
    },
    "card_details": {
      "encryption_key_id": "5EE0",
      "encrypted_card_data": "34363136363937323538313530393338443235303444323539",
      "encryption_ksn": "123456789012"
    },
    "transacted_at": "2024-01-15T10:30:00.000Z"
  }'

Refunds

Endpoint: POST /v3/refunds

When to use:

• Customer requests refund for completed transaction
• Partial or full refund scenarios
• Returns processing

Example Scenario:
Processing a €30 partial refund from a €50 transaction:

# Process refund
curl -X POST "https://base-url.salt/api/v3/refunds" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-67890" \
  -d '{
    "transaction_id": "tr_87de9bea-b32d-4ef5-a481-b8ba48764325",
    "terminal_id": "12345678",
    "amount": 3000
  }'