Follow the steps below to access the Cybersouce authorisation details via the Submarine Payments API.

Prerequisites

Step 1

Contact Cybersource to enable the Token Management Service for your account.

The Token Management Service allows to generate the payment instrument tokens during the authorisation call and is required to use the Submarine Payments API.

Step 2

Provide the Cybersource credentials during the onboarding. More details can be found here:

Submarine Payments API

GraphQL endpoint

All queries are executed by sending POST HTTP requests to:

json
https://submarine-payments.submarineplatform.com/graphql

Authentication

Every request to the API requires a valid access token.

The access token is created during onboarding and can be found in the Submarine API access section.

The access token should be presented in the Authorization header as a bearer token.

The Shopify domain needs to be provided in the X-Shopify-Domain header.

Provide the following headers with each request:

json
Authorization: Bearer <insert your access token here>

X-Shopify-Domain: your-shopify-domain.myshopify.com

Accept: application/json

Content-Type: application/json

paymentSession API

The paymentSession GraphQL query allows to retrieve the Cybersource authorisation details.

Required ID

An ID is required to retrieve the payment session information via the paymentSession GraphQL endpoint.

The ID needs to be provided with every request as a GraphQL variable. Here’s an example of the ID:

json
gid://external/PaymentSession/rOeHMOmaTosfqpW9TBc9o7ael

The ID can be found in the Shopify order transaction data as a payment_id.

The ID is then referenced in Cybersource UI as a Merchant Reference Number.

Example request

graphql
query paymentSession($id: SharedGlobalID!) {
  paymentSession(id: $id) {
    amount {
      amount
      currency
    }
    channelIdentifier
    customer {
      billingAddress {
        city
        country
        firstName
        lastName
        line1
        line2
        postalCode
        state
      }
      email
      phoneNumber
      shippingAddress {
        city
        country
        firstName
        lastName
        line1
        line2
        postalCode
        state
      }
    }
    externalId
    group
    id
    merchantLocale
    paymentKind
    status
    test
    vaultedPaymentMethod {
      id
      initialCharge {
        amount {
          amount
          currency
        }
        failureCode
        failureMessage
        metadata
        status
        token
        type
      }
      paymentInstrument {
        card {
          brand
          expiry {
            month
            year
          }
          last4
        }
        status
        token
        type
      }
    }
  }
}

Example response

json
{
  "data": {
    "paymentSession": {
      "amount": {
        "amount": "499.00",
        "currency": "USD"
      },
      "channelIdentifier": "example-shop.myshopify.com",
      "customer": {
        "billingAddress": {
          "city": "Cremorne",
          "country": "AU",
          "firstName": "Amy",
          "lastName": "Jones",
          "line1": "10-20 Gwynne Street",
          "line2": null,
          "postalCode": "3121",
          "state": "Victoria"
        },
        "email": "amy.jones@gmail.com",
        "phoneNumber": null,
        "shippingAddress": {
          "city": "Cremorne",
          "country": "AU",
          "firstName": "Amy",
          "lastName": "Jones",
          "line1": "10-20 Gwynne Street",
          "line2": null,
          "postalCode": "3121",
          "state": "Victoria"
        }
      },
      "externalId": "rOeHMOmaTosfqpW9TBc9o7ael",
      "group": "5riaRnIuFyUK+kODHU+1STD/bHswfkwYWMooqdXqla0=",
      "id": "gid://submarine-payments/PaymentSession/018e7e52-b64a-5ef2-6c2a-c5c85dddfeaa",
      "merchantLocale": "en-AU",
      "paymentKind": "AUTH",
      "status": "RESOLVED",
      "test": true,
      "vaultedPaymentMethod": {
        "id": "gid://submarine-payments/VaultedPaymentMethod/018e7e52-b652-9ac6-ab90-0fa5f75d5686",
        "initialCharge": {
          "amount": {
            "amount": "499.00",
            "currency": "USD"
          },
          "failureCode": null,
          "failureMessage": null,
          "metadata": {
            "created_at": "2024-03-27T05:12:14Z",
            "reconciliation_id": "7D7PCU79XUWL",
            "client_reference_code": "rOeHMOmaTosfqpW9TBc9o7ael",
            "payment_network_transaction_id": "016150703802094"
          },
          "status": "SUCCEEDED",
          "token": "7115163338006409504953",
          "type": "AUTHORISE"
        },
        "paymentInstrument": {
          "card": {
            "brand": "VISA",
            "expiry": {
              "month": 8,
              "year": 2025
            },
            "last4": "4242"
          },
          "status": "SUCCEEDED",
          "token": "149E5D0A0F49F946E063AF598E0A9E88",
          "type": "CARD"
        }
      }
    }
  }
}

Authorisation details

Tokens

Note: All tokens are redacted by default. After completing the onboarding steps, the Submarine Payments team will update the default configuration for you.

Payment instrument token

A payment instrument token can be used to make calls to Cybersource directly. Use the following query to access the token:

graphql
query paymentSession($id: SharedGlobalID!) {
  paymentSession(id: $id) {
    vaultedPaymentMethod {
      paymentInstrument {
        token
    	}
    }
  }
}

json
{
  "data": {
    "paymentSession": {
      "vaultedPaymentMethod": {
        "paymentInstrument": {
          "token": "149E5D0A0F49F946E063AF598E0A9E88"
        }
      }
    }
  }
}

Cybersource - Authorization Use Case