Payment Requests with Vortex Envelope

This page provides guidance on how to process card payments using the Broker Client Library, detailing sample payment payloads, JavaScript code examples, and instructions on how to interact with the payment system for various transaction types.

In this guide, you'll find:

Sample payloads for payment processing, including transaction details for Visa, MasterCard, American Express, and Discover.
JavaScript code examples demonstrating how to create and retrieve payment transactions using the Broker Client Library.
Step-by-step instructions on how to implement the PaymentClient and handle responses, including authorization codes and payment statuses.

Vortex Envelope - Card Payments

The Vortex Envelope provides a standardized framework for initiating and managing card payment requests within the Vortex system. This guide explains how to structure payment requests, authorize card payments, and retrieve payment details efficiently and securely.

BTo process a card payment in Vortex:

Construct a JSON-RPC formatted envelope.
Populate the arguments array with a valid card transaction payload.
Send the request to the Vortex payment gateway.
Handle the response, including authorization details and status.

1. Vortex Envelope Structure

Every card payment request must be wrapped in a standard Vortex envelope:

{
  "arguments": [
    {
      "__payment_transaction_payload_as_JSON__"
    }
  ],
  "procedure": "card.create",
  "class": "rpc",
  "requestId": "__UUID__"
}

Envelope Fields

Field	Description
`arguments`	An array containing one object: the payment transaction payload.
`procedure`	Specifies the RPC procedure to execute. For card payments, use `card.create`.
`class`	Always `"rpc"` for remote procedure calls.
`requestId`	A unique identifier (UUID) used to trace the request.

2. Constructing a Card Payment Payload

The core of the request is the payment transaction payload, which contains all necessary details including card info, merchant data, transaction metadata, and device configuration.

Below are examples for each major card network. Replace the placeholder values with real transaction data.

3. Sample Card Payment Payloads

Each payload demonstrates a typical Sale transaction for a different card network.

American Express

// Replace placeholder values for production use
{
  "transactionType": "Sale",
  "totalAmount": 0.02,
  "currencyCode": "840",
  "externalId": "859254563560560",
  "merchant": {
    "accountId": "261559",
    "name": "PPS Engineering UAT 2",
    "americanExpress": {
      "number": "6011040438"
    },
    "address": {
      "street1": "2001 Westside",
      "city": "Alpharetta",
      "state": "GA",
      "postalCode": "30004",
      "country": "USA"
    }
    // ... other merchant fields
  },
  "account": {
    "network": "americanExpress",
    "number": "371111111111114",
    "expiry": "2025-12",
    "accountHolderName": "bury",
    "securityCode": "7657"
  },
  "device": {
    "accountCaptureMethod": "Manual",
    "cardPresent": true
    // ... other device fields
  },
  "invoice": {
    "number": "345656",
    "lineItems": [
      {
        "description": "groceries",
        "quantity": 5,
        "unitCost": 3
        // ... other line item fields
      }
    ]
  }
}

Discover

{
  "transactionType": "Sale",
  "totalAmount": 0.02,
  "currencyCode": "840",
  "externalId": "859254563560560",
  "merchant": {
    "name": "PPS Engineering UAT 2",
    "discover": {
      "number": "601104043838335"
    }
    // ... other merchant fields
  },
  "account": {
    "network": "discover",
    "number": "6011111111111117",
    "expiry": "2025-12",
    "accountHolderName": "bury"
  },
  "device": {
    "accountCaptureMethod": "Manual",
    "cardPresent": true
  }
  // ... other fields
}

Visa

{
  "transactionType": "Sale",
  "totalAmount": 10.01,
  "externalId": "9459934922998",
  "merchant": {
    "name": "Merchant Account",
    "processor": { "name": "TSYS" },
    "sponsor": { "bin": "5678", "ica": "9876" }
  },
  "account": {
    "network": "Visa",
    "number": "4242424242424242",
    "expiry": "2022-06-30T23:59:59",
    "avsStreet": "1234 red lane",
    "avsPostalCode": "30114"
  },
  "device": {
    "accountCaptureMethod": "manual"
  },
  "invoice": {
    "number": "1234567890",
    "lineItems": [
      {
        "description": "groceries",
        "quantity": "4",
        "unitCost": 50
      }
    ]
  }
}

MasterCard

{
  "transactionType": "Sale",
  "totalAmount": 0.01,
  "externalId": "9459934922998",
  "merchant": {
    "name": "Merchant Account",
    "sponsor": {
      "bin": "5678",
      "ica": "9876"
    }
  },
  "account": {
    "network": "MasterCard",
    "number": "5594330000000002",
    "expiry": "2022-06-30T23:59:59"
  },
  "device": {
    "accountCaptureMethod": "Swipe",
    "cardPresent": true
  },
  "invoice": {
    "number": "1234567890",
    "lineItems": [
      {
        "description": "description of the lineItem",
        "quantity": "4",
        "unitCost": 50
      }
    ]
  }
}

4. Sample Response Structure

On successful processing, Vortex returns a JSON object with authorization results and metadata.

Successful Amex Transaction

{
  "code": 200,
  "error": null,
  "value": {
    "amount": 0.02,
    "approved": true,
    "authCode": "DSC600",
    "authorization": {
      "authorized": true,
      "deviceId": "9876",
      "processingTime": "00:00:00.2883801"
    }
  }
}

Field	Description
`code`	HTTP-style status code; 200 indicates success.
`approved`	Boolean indicating if the transaction was approved.
`authCode`	Issuer authorization code.
`processingTime`	Time taken to complete the request.

5. Security Considerations

PCI DSS Compliance: Always secure cardholder data in transit and at rest.
Tokenization: Where available, use tokens instead of raw PANs.
UUID Usage: Ensure requestId values are unique to prevent replay attacks.