Cybersource - Authorization Use Case

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


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.
Image without caption

Step 2

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

Submarine Payments API

GraphQL endpoint

All queries are executed by sending POST HTTP requests to:


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.
Image without caption
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:
Authorization: Bearer <insert your access token here> X-Shopify-Domain: 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:
The ID can be found in the Shopify order transaction data as a payment_id.
Image without caption
The ID is then referenced in Cybersource UI as a Merchant Reference Number.
Image without caption

Example request

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

{ "data": { "paymentSession": { "amount": { "amount": "499.00", "currency": "USD" }, "channelIdentifier": "", "customer": { "billingAddress": { "city": "Cremorne", "country": "AU", "firstName": "Amy", "lastName": "Jones", "line1": "10-20 Gwynne Street", "line2": null, "postalCode": "3121", "state": "Victoria" }, "email": "", "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

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:
query paymentSession($id: SharedGlobalID!) { paymentSession(id: $id) { vaultedPaymentMethod { paymentInstrument { token } } } }
{ "data": { "paymentSession": { "vaultedPaymentMethod": { "paymentInstrument": { "token": "149E5D0A0F49F946E063AF598E0A9E88" } } } } }
Image without caption