Cybersource - Authorization Use Case

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 for using 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:
json
https://submarine-payments.getsubmarine.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.
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:
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/rvi1bn3jJuDBVjuRTjEjdIyok
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 as a Merchant Reference Number.
Image without caption

Example request

graphql
query paymentSession($id: SharedGlobalID!) { paymentSession(id: $id) { amount { amount currency } channelIdentifier customer { billingAddress { city country firstName lastName line1 postalCode state } email phoneNumber shippingAddress { city country firstName lastName line1 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", "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", "postalCode": "3121", "state": "Victoria" } }, "externalId": "rvi1bn3jJuDBVjuRTjEjdIyok", "group": "wmItEHtkPJ+Mmnlbw4H24hV2QMAO22zDJJT05Ic8n8o=", "id": "gid://platform-shopify-ppp/PaymentSession/018d9ab7-cb24-0f10-bcd3-7cc30c0b6d76", "merchantLocale": "en-AU", "paymentKind": "AUTH", "status": "RESOLVED", "test": true, "vaultedPaymentMethod": { "id": "gid://platform-shopify-ppp/VaultedPaymentMethod/018d9ab7-cb38-b971-7731-cc92053102d9", "initialCharge": { "amount": { "amount": "499.00", "currency": "USD" }, "failureCode": null, "failureMessage": null, "metadata": { "client_reference_code": "rvi1bn3jJuDBVjuRTjEjdIyok", "created_at": "2024-02-12T00:29:13Z", "payment_network_transaction_id": "016150703802094", "reconciliation_id": "GE9R6RYJ4BBS" }, "status": "SUCCEEDED", "token": "7076977530576840304953", "type": "AUTH" }, "paymentInstrument": { "card": { "brand": "VISA", "expiry": { "month": 8, "year": 2025 }, "last4": "4242" }, "status": "SUCCEEDED", "token": "112553EB4FC99203E063AF598E0A377E", "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": "112553EB4FC99203E063AF598E0A377E" } } } } }
Image without caption