Payment Requests with Vortex Envelope

The Vortex Envelope provides a standardized template for initiating card payment requests within the Vortex system. This envelope encapsulates the necessary details for transaction processing, ensuring secure and efficient handling of payment information.

Vortex Envelope - Card Payments

Below is the template for a card payment request using the Vortex Envelope. This template outlines the structure for submitting a card payment transaction, where the payload contains all relevant payment information in JSON format.

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

arguments: This array holds the payment transaction payload, where you replace __payment_transaction_payload_as_JSON__ with your actual payment data structured as JSON.
procedure: Defines the specific action to be taken. For card payments, this is set to card.create.
class: Indicates the type of operation; in this case, rpc (Remote Procedure Call) is used for executing a predefined function.
requestId: A unique identifier for the request, typically a UUID, ensuring traceability and non-repudiation.

Request Authorization for Card Payment

To authorize a card payment, construct your payload with the necessary payment details, such as the card number, expiration date, amount, and currency. Ensure sensitive information is handled securely, complying with PCI DSS standards.

Sample Payloads

Below are examples of sample payloads for different types of card payment requests. Replace the placeholders with actual data relevant to your transaction..

{
  "cashbackAmount":0,
  "ecom":false,
  "moto":false,
  "externalId":"859254563560560",
  "transactionType":"Sale",
  "totalAmount":0.02,
  "currencyCode":"840",
  "merchant":{
    		"accountId":"261559",
        "name":"PPS Engineering UAT 2",
        "sic":"7399",
        "address":{
          	"street1":"2001 Westside",
            "city":"Alpharetta",
            "state":"GA",
            "postalCode":"30004",
            "country":"USA"},
        "number":"518089240725465",
        "email":"[email protected]",
        "phone":"678-222-3333",
        "processor":{
          	"name":"FIS",
            "bankNumber":"8739"},
        "sponsor":{
          	"ica":"3583",
            "bin":"470780"},
        "taxId":"123456789",
        "businessType":"retail",
        "legalEntity":"SCorp",
        "americanExpress":{
          	"number":"601104043838335"}
  		},
  "meta":{
    	"created":"2022-09-29 21:06:33"},
  "account":{
      "form":"Plastic",
      "network":"americanExpress",
      "expiry":"2025-12",
      "sequence":0,
      "number":"6011111111111117",
      "accountHolderName":"bury",
      "securityCode":"765",
      "avsPostalCode":"75200",
      "avsStreet":"street 10"},
   "device":{
     	"accountCaptureMethod":"Manual",
      "cardPresent":true,
      "cardholderPresence":"Present",
      "attendance":"Attended",
      "location":"OnPremise",
      "inputCapability":"SwipeKeyed",
      "id":"9876",
      "pinCaptureCapability":"Capable",
      "catLevel":"None",
      "transactionSecurity":"Normal",
      "partialApprovalSupport":"Supported"},
   "reference":"false",
   "requestedAmount":0.02,
   "originalAmount":0,
   "taxAmount":0,
   "recurring":false,
   "environment":"default",
   "tipAmount":0.01,
   "surchargeAmount":0.01,
   "dynamicDescriptor":"purchased groceries",
   "bankNetDate":"2022-12-12",
   "bankNetReferenceNumber":"6066135524",
   "ecommerceSecurityLevelIndicator":"324",
   "submerchant":{
     	"facilitatorId":"7654",
      "merchantId":"3456"},
   "customer":{
     	"name":"john mark",
      "firstName":"john",
      "lastName":"mark",
      "address":{
        	"street1":"street 859",
          "street2":"street 62",
          "state":"GA",
          "city":"Alpharetta",
          "postalCode":"30030",
          "country":"USA"},
      "phone":"9876543210",
      "email":"[email protected]",
      "number":"9876543",
      "taxId":"987654321"},
   "shippingAddress":{
     	"street2":"Street 53",
      "street1":"Street 10",
      "city":"Alpharetta",
      "state":"GA",
      "postalCode":"30004",
      "country":"USA"},
   "aciRequest":"AVS",
   "invoiceNumber":"34554",
   "invoice":{
     	"number":"345656",
      "discountRate":23,
      "discountAmount":0.01,
      "taxAmount":0.5,
      "taxRate":3,
      "taxExempt":false,
      "dutyAmount":1.07,
      "freightAmount":1.87,
      "freightTaxAmount":1.45,
      "freightTaxRate":5,
      "destinationPostalCode":"30004",
      "sourcePostalCode":"30004",
      "destinationCountry":"USA",
      "lineItems":[
        	{
            "commodityCode":"876569",
            "description":"groceries",
            "productCode":"987378",
            "unit":"3",
            "quantity":5,
            "unitCost":3,
            "discountRate":4,
            "discountAmount":1.83,
            "taxRate":3,
            "taxAmount":1.53,
            "dutyAmount":2.71,
            "extendedAmount":1.88,
            "freightAmount":1.04,
            "freightTaxAmount":3.51,
            "freightTaxRate":5}
      ]
   }
}

{
  "cashbackAmount":0,
  "ecom":false,
  "moto":false,
  "externalId":"859254563560560",
  "transactionType":"Sale",
  "totalAmount":0.02,
  "currencyCode":"840",
  "merchant":{
    		"accountId":"261559",
        "name":"PPS Engineering UAT 2",
        "sic":"7399",
        "address":{
          	"street1":"2001 Westside",
            "city":"Alpharetta",
            "state":"GA",
            "postalCode":"30004",
            "country":"USA"},
        "number":"518089240725465",
        "email":"[email protected]",
        "phone":"678-222-3333",
        "processor":{
          	"name":"FIS",
            "bankNumber":"8739"},
        "sponsor":{
          	"ica":"3583",
            "bin":"470780"},
        "taxId":"123456789",
        "businessType":"retail",
        "legalEntity":"SCorp",
        "discover":{
          	"number":"601104043838335"}
  		},
  "meta":{
    	"created":"2022-09-29 21:06:33"},
  "account":{
    	"form":"Plastic",
      "network":"discover",
      "expiry":"2025-12",
      "sequence":0,
      "number":"6011111111111117",
      "accountHolderName":"bury",
      "securityCode":"765",
      "avsPostalCode":"75200",
      "avsStreet":"street 10"},
   "device":{
     	"accountCaptureMethod":"Manual",
      "cardPresent":true,
      "cardholderPresence":"Present",
      "attendance":"Attended",
      "location":"OnPremise",
      "inputCapability":"SwipeKeyed",
      "id":"9876",
      "pinCaptureCapability":"Capable",
      "catLevel":"None",
      "transactionSecurity":"Normal",
      "partialApprovalSupport":"Supported"},
   "reference":"false",
   "requestedAmount":0.02,
   "originalAmount":0,
   "taxAmount":0,
   "recurring":false,
   "environment":"default",
   "tipAmount":0.01,
   "surchargeAmount":0.01,
   "dynamicDescriptor":"purchased groceries",
   "bankNetDate":"2022-12-12",
   "bankNetReferenceNumber":"6066135524",
   "ecommerceSecurityLevelIndicator":"324",
   "submerchant":{
     	"facilitatorId":"7654",
      "merchantId":"3456"},
   "customer":{
     	"name":"john mark",
      "firstName":"john",
      "lastName":"mark",
      "address":{
        	"street1":"street 859",
          "street2":"street 62",
          "state":"GA",
          "city":"Alpharetta",
          "postalCode":"30030",
          "country":"USA"},
      "phone":"9876543210",
      "email":"[email protected]",
      "number":"9876543",
      "taxId":"987654321"},
   "shippingAddress":{
     	"street2":"Street 53",
      "street1":"Street 10",
      "city":"Alpharetta",
      "state":"GA",
      "postalCode":"30004",
      "country":"USA"},
   "aciRequest":"AVS",
   "invoiceNumber":"34554",
   "invoice":{
     	"number":"345656",
      "discountRate":23,
      "discountAmount":0.01,
      "taxAmount":0.5,
      "taxRate":3,
      "taxExempt":false,
      "dutyAmount":1.07,
      "freightAmount":1.87,
      "freightTaxAmount":1.45,
      "freightTaxRate":5,
      "destinationPostalCode":"30004",
      "sourcePostalCode":"30004",
      "destinationCountry":"USA",
      "lineItems":[
        	{
            "commodityCode":"876569",
            "description":"groceries",
            "productCode":"987378",
            "unit":"3",
            "quantity":5,
            "unitCost":3,
            "discountRate":4,
            "discountAmount":1.83,
            "taxRate":3,
            "taxAmount":1.53,
            "dutyAmount":2.71,
            "extendedAmount":1.88,
            "freightAmount":1.04,
            "freightTaxAmount":3.51,
            "freightTaxRate":5}
      ]
   }
}

{
    cashbackAmount: 0.0,
    ecom: false,
    moto: false,
    externalId: '9459934922998',
    originalExternalId: '9459934922998',
    transactionType: 'Sale',
    totalAmount: 0.01,
    merchant: {
        accountId: '471492222',
        name: 'Merchant Account',
        sic: '5399',
        address: {
            street1: '2001 Westside',
            city: 'Alpharetta',
            state: 'GA',
            postalCode: '30004',
            country: 'USA'
        },
        number: '8739290856487003',
        processor: {
            name: 'TSYS',
            bankNumber: '1234',
        },
        sponsor: {
            bin: '5678',
            ica: '9876'
        }
    },
    meta: {
        created: '2020-12-15T17:00:01.8201195-04:00'
    },
    account: {
        number: '4242424242424242',
        form: 'Plastic',
        network: 'Visa',
        expiry: '2022-06-30T23:59:59',
        avsPostalCode: '30114',
        avsStreet: '1234 red lane'
    },
    device: {
        accountCaptureMethod: 'Swipe',
        cardPresent: true,
        cardholderPresence: 'Present',
        attendance: 'Attended',
        location: 'OnPremise',
        inputCapability: 'SwipeKeyed'
    },
    reference: '09498540',
    requestedAmount: 0.01,
    originalAmount: 0.01,
    taxAmount: 0.0,
    recurring: false,
    invoice: {
        number: '1234567890',
        taxAmount: '$40',
        taxRate: '30',
        dutyAmount: '$2',
        discountRate: '10',
        discountAmount: '$20',

        freightAmount: '$50',
        freightTaxAmount: '$3',
        freightTaxRate: '6',

        sourcePostalCode: '30062',
        destinationPostalCode: '20202',
        destinationCountry: 'United States',

        lineItems:[
            {
                commodityCode: 'commodityCode',
                description: 'description of the lineItem',
                productCode: 'az123jf45ty',
                quantity: '4',
                unit: 'unit string',
                unitCost: '$50',

                discountRate: '10',
                discountAmount: '$10',
                taxRate: '5',
                taxAmount: '$5',
                dutyAmount: '$2',
                extendedAmount: '$4',

                freightAmount: '$10',
                freightTaxAmount: '$5',
                freightTaxRate: '5',
            }
        ]
    }
}

{
    cashbackAmount: 0.0,
    ecom: false,
    moto: false,
    externalId: '9459934922998',
    originalExternalId: '9459934922998',
    transactionType: 'Sale',
    totalAmount: 0.01,
    merchant: {
        accountId: '471492222',
        name: 'Merchant Account',
        sic: '5399',
        address: {
            street1: '2001 Westside',
            city: 'Alpharetta',
            state: 'GA',
            postalCode: '30004',
            country: 'USA'
        },
        number: '8739290856487003',
        processor: {
            name: 'TSYS',
            bankNumber: '1234',
        },
        sponsor: {
            bin: '5678',
            ica: '9876'
        }
    },
    meta: {
        created: '2020-12-15T17:00:01.8201195-04:00'
    },
    account: {
        number: '4242424242424242',
        form: 'Plastic',
        network: 'Visa',
        expiry: '2022-06-30T23:59:59',
        avsPostalCode: '30114',
        avsStreet: '1234 red lane'
    },
    device: {
        accountCaptureMethod: 'Swipe',
        cardPresent: true,
        cardholderPresence: 'Present',
        attendance: 'Attended',
        location: 'OnPremise',
        inputCapability: 'SwipeKeyed'
    },
    reference: '09498540',
    requestedAmount: 0.01,
    originalAmount: 0.01,
    taxAmount: 0.0,
    recurring: false,
    invoice: {
        number: '1234567890',
        taxAmount: '$40',
        taxRate: '30',
        dutyAmount: '$2',
        discountRate: '10',
        discountAmount: '$20',

        freightAmount: '$50',
        freightTaxAmount: '$3',
        freightTaxRate: '6',

        sourcePostalCode: '30062',
        destinationPostalCode: '20202',
        destinationCountry: 'United States',

        lineItems:[
            {
                commodityCode: 'commodityCode',
                description: 'description of the lineItem',
                productCode: 'az123jf45ty',
                quantity: '4',
                unit: 'unit string',
                unitCost: '$50',

                discountRate: '10',
                discountAmount: '$10',
                taxRate: '5',
                taxAmount: '$5',
                dutyAmount: '$2',
                extendedAmount: '$4',

                freightAmount: '$10',
                freightTaxAmount: '$5',
                freightTaxRate: '5',
            }
        ]
    }
}

Sample Responses

{
    "code": 200,
    "error": null,
    "value": {
        "amount": 0.02,
        "approved": true,
        "authCode": "DSC600",
        "authorization": {
            "acceptorId": "601104043838335",
            "accountCaptureMethod": 1,
            "authorized": true,
            "deviceId": "9876",
            "processingTime": "00:00:00.2883801",
            "request": "MDEwMPI8ZxGI4IAOAAAAAAAAAAYxNjYwMTExMTAwMDAwMDExMTcwMDAwMDAwMDAwMDAwMDAwMDIwOTI5MjEwNjMzNDkyMTcyMjEwNjMzMDkyOTI1MTI3Mzk5ODQwMDEwMDAwMTAwRDAwMDAwMDAxMDY2NTA1ODYwNjYxMDk5MzIyNzIyMTQ5MjE3MjAwMDA5ODc2NjAxMTA0MDQzODM4MzM1UFJUKnB1cmNoYXNlZCBncm9jZXJpZSBBbHBoYXJldHRhICAgIEdBIDg0MDAxMzAxMDAwOTAwMTA3MDAwNjAyMDAxIFdlc3RzaWRlICAgICAgICAgMzAwMDQwMDAwODQwICAgICAgICAgICAgICAgICAgICAgICAgICAwMTQ3NTIwMCAgICAxMCAgIDAwNTE3NjUgMDA1MDMxNDE=",
            "response": "MDExMBIiABAOEQIAMDAwMDAwMDAwMDAyMDkyOTIxMDYzMzQ5MjE3MjA5MjlEMDAwMDAwMDEyMjcyMjE0OTIxNzJEU0M2MDAwMDE0QSAgICAgICAgICAgIDIwMjUgICAgICAgICAgMDYwMDAwMDAwMDcxMDEwMDEykQocAaLFxoOgcDAw",
            "responseCode": "00",
            "reversed": false
        },
        "code": 0,
        "declined": false,
        "emvResponse": "kQocAaLFxoOgcDAwigIwMA==",
        "lossPrevention": {
            "avsCode": "Y",
            "securityCode": "M"
        },
        "message": "Approved or completed successfully",
        "originalAmount": 0.02,
        "reference": "227221492172",
        "requestedAmount": 0.02,
        "reversed": false,
        "transactionId": "060000000071010",
        "id": "371CKSy0zQ45zslsiI1lkw=="
    },
    "class": "response",
    "id": "4d65bcd5-1bf2-57e6-b90c-ad0156aaf29d",
    "requestId": "Field_Level_Validations_Discover0.1782"
}

{
    "code": 200,
    "error": null,
    "value": {
        "amount": 0.02,
        "approved": true,
        "authCode": "DSC600",
        "authorization": {
            "acceptorId": "601104043838335",
            "accountCaptureMethod": 1,
            "authorized": true,
            "deviceId": "9876",
            "processingTime": "00:00:00.2883801",
            "request": "MDEwMPI8ZxGI4IAOAAAAAAAAAAYxNjYwMTExMTAwMDAwMDExMTcwMDAwMDAwMDAwMDAwMDAwMDIwOTI5MjEwNjMzNDkyMTcyMjEwNjMzMDkyOTI1MTI3Mzk5ODQwMDEwMDAwMTAwRDAwMDAwMDAxMDY2NTA1ODYwNjYxMDk5MzIyNzIyMTQ5MjE3MjAwMDA5ODc2NjAxMTA0MDQzODM4MzM1UFJUKnB1cmNoYXNlZCBncm9jZXJpZSBBbHBoYXJldHRhICAgIEdBIDg0MDAxMzAxMDAwOTAwMTA3MDAwNjAyMDAxIFdlc3RzaWRlICAgICAgICAgMzAwMDQwMDAwODQwICAgICAgICAgICAgICAgICAgICAgICAgICAwMTQ3NTIwMCAgICAxMCAgIDAwNTE3NjUgMDA1MDMxNDE=",
            "response": "MDExMBIiABAOEQIAMDAwMDAwMDAwMDAyMDkyOTIxMDYzMzQ5MjE3MjA5MjlEMDAwMDAwMDEyMjcyMjE0OTIxNzJEU0M2MDAwMDE0QSAgICAgICAgICAgIDIwMjUgICAgICAgICAgMDYwMDAwMDAwMDcxMDEwMDEykQocAaLFxoOgcDAw",
            "responseCode": "00",
            "reversed": false
        },
        "code": 0,
        "declined": false,
        "emvResponse": "kQocAaLFxoOgcDAwigIwMA==",
        "lossPrevention": {
            "avsCode": "Y",
            "securityCode": "M"
        },
        "message": "Approved or completed successfully",
        "originalAmount": 0.02,
        "reference": "227221492172",
        "requestedAmount": 0.02,
        "reversed": false,
        "transactionId": "060000000071010",
        "id": "371CKSy0zQ45zslsiI1lkw=="
    },
    "class": "response",
    "id": "cf968a0b-9484-5044-b622-dbfa7da3e20b",
    "requestId": "Field_Level_Validations_Discover0.1782"
}

JavaScript with the Broker Client Library

Enhance your card payment requests with the Broker Client Library. This example demonstrates how to initiate a payment transaction using JavaScript:

// Code Example 1: Create a Card Payment Transaction
const broker = require('@pps/broker-client');
const client = new broker.PaymentClient('EOS_YOUR_TENANT_TOKEN'); // Replace EOS_YOUR_TENANT_TOKEN with your actual tenant token

async function createCardPayment() {
    try {
        await client.open();
        const transaction = {
            // Insert your transaction details here. Refer to the Sample Payloads section for structure.
        };
        const response = await client.rpc.card.create(transaction);
        console.log(`Transaction ID: ${response.id}, Message: ${response.message}`);
    } catch (error) {
        console.error('Transaction failed:', error);
    } finally {
        await client.close();
    }
}

createCardPayment();

Ensure to replace EOS_YOUR_TENANT_TOKEN with your specific tenant token and provide the transaction details in the specified section.

Retrieving Payment Information with GET Route

Retrieve specific payment transaction information using the Payment GET Route. This code snippet illustrates how to fetch a payment by its external ID:

// Code Example 2: Fetch Payment Transaction by External ID
const {PaymentClient} = require('@pps/broker-client');
const client = new PaymentClient('EOS_TENANT_TOKEN', 'environment'); // Provide your tenant token and environment

async function getPaymentById(externalId) {
    try {
        await client.open();
        const paymentInfo = await client.rpc.card.get(externalId); // Replace 'some-external-id' with the actual ID
        console.log(`Payment Info: ${paymentInfo}`);
    } catch (error) {
        console.error('Failed to retrieve payment:', error);
    } finally {
        await client.close();
    }
}

getPaymentById('some-external-id'); // Example call with a placeholder ID

Replace EOS_TENANT_TOKEN and 'some-external-id' with your actual tenant token and the external ID of the payment transaction you wish to retrieve, respectively.