Build a credit card payments extensions with Shopify CLI

Beta

Processing a payment with a credit card payments extension is supported as of API version 2023-04 and is currently in an invite-only closed beta.

All Partners must submit a valid Payment Card Industry (PCI) Attestation of Compliance (AOC) before access to credit card payment extension is granted.

Tip

To create payment extensions via Shopify CLI you must be using v3.60.0 or above.

Credit card payments extensions allow customers to complete the payment process directly on the merchant's website, with additional features such as 3DS authentication.

When a store enables your credit card payments extension, credit card payments are processed by your extension, directly in Shopify checkout. When a customer then enters their credit card details into checkout, Shopify sends the payment details to your payments extension, which processes the payment and returns the result to Shopify, while the customer remains on the storefront.

To make a production-ready extension, you need to make several changes to the template code to include your own payment processing capabilities. This tutorial highlights the areas you need to edit or extend with your own functionality.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

Set up your app using the Remix template for credit card payments apps
Create a credit card payments extension
Explore the payment, refund, void, reject and capture session flows, and how to implement them yourself
Configure 3-D Secure authentication
Deploy new versions of your payments extension

Requirements

Create a Partner account

Create a development store

The development store should be pre-populated with test data.

Become a Payments Partner

Apply and receive approval to become a Payments Partner.

Create an encryption certificate

An encryption certificate is required to decrypt credit card information in your PCI DSS compliant environment.

Project

Framework:

View on GitHub

Anchor to Create a payments appCreate a payments app

Create a new payments app using Shopify CLI.

Anchor to Scaffold an app using Shopify CLIScaffold an app using Shopify CLI

Run the following command to start creating your app:
Terminal
npm init @shopify/app@latest
When prompted, enter the name of your app.
When prompted for the approach, select the following option to add your first extension:
Terminal
Build a Remix app (recommended)
> Build an extension-only app

Anchor to Create a payments extensionCreate a payments extension

Your Shopify app becomes a payments app after you've created and configured your payments extension.

Run the following command to start generating your payment extension:
Terminal
pnpm shopify app generate extension
When prompted, choose your organization and create a new app.
When prompted for Type of extension, select Payments App Extension > Credit Card and name your extension.

Anchor to Configure your payments extensionConfigure your payments extension

When you generate an extension, a TOML configuration file named shopify.extension.toml is automatically generated in your app's extension directory. You can find your extension configuration in extensions/<extension-name>/shopify.extensions.toml.

Property name	Description
`payment_session_url` required	The URL that receives payment and order details from the checkout.
`refund_session_url` required	The URL that refund session requests are sent to.
`capture_session_url` required	The URL that capture session requests are sent to.
`void_session_url` required	The URL that void session requests are sent to.
`confirmation_callback_url` optional	The URL that confirm session requests are sent to. This URL is required if your payments app supports 3-D Secure authentication.
`supported_countries` required	The countries where your payments app is available. List of ISO 3166 (alpha-2) country codes your app is available for installation by merchants. Learn more: https://www.iso.org/iso-3166-country-codes.html
`supports_moto` required	Enables Mail Order/Telephone Order (MOTO), allowing merchants to manually process transactions using a customer's credit card information. The `moto` attribute in payment method data is only available in API version 2024-07 and later.
`supports_3ds` required	3-D Secure support is mandated in some instances. For example, you must enable the 3-D Secure field if you plan to support payments in countries which have mandated 3-D Secure.
`supported_payment_methods` required	The payment methods (for example, Visa) that are available with your payments app. Learn more: https://github.com/activemerchant/payment_icons/blob/master/db/payment_icons.yml
`supports_installments` required	Enables installments
`supports_deferred_payments` required	Enables deferred payments
`merchant_label` required	The name for your payment provider extension. This name is displayed to merchants in the Shopify admin when they search for payment methods to add to their store. Limited to 50 characters.
`test_mode_available` required	Enables merchants using your payments app to test their setup by simulating transactions. To test your app on a development store, your payment provider in the Shopify admin must be set to test mode.
`api_version` required	The Payments Apps GraphQL API version used by the payment provider app to receive requests from Shopify. You must use the same API version for sending GraphQL requests. You can't use the unstable version of the API in production. API versions are updated in accordance with Shopify's general API versioning timelines.
`multiple_capture` optional, closed beta	Enables merchants using your payment provider app to partially capture an authorized payment multiple times up to the full authorization amount. This is used only if your payments app supports merchant manual capture.
`encryption_certificate_fingerprint` required	The certificate that Shopify uses to generate the ephemeral key and encrypt the credit card information of the customer. Refer to manage encryption certificates section to learn more.

Anchor to Set up your payments appSet up your payments app

Anchor to Disable embeddingDisable embedding

Shopify apps are embedded by default, but payments apps are an exception to this, because they don't need to render anything in Shopify admin. In shopify.app.toml, update the embedded and set it to false.

Anchor to Configure basic app settingsConfigure basic app settings

In shopify.app.toml, update the name and client_id to match the information about the app that you manually created. You can find the client_id in the Client credentials section of your app's overview page in the Partner Dashboard.

Anchor to Start your development serverStart your development server

To run the app locally, start your development server:

Install the packages required to run the payments app:

Terminal
npm install
yarn install
pnpm install
npm installyarn installpnpm install
Run the following command:

Terminal
shopify app dev

Info
You might be prompted to log in to your Partner account.

In your terminal, select your development store. You can use the generated URL to test your payments app by using it in your payments app configuration. If you want a consistent tunnel URL, then you can use the --tunnel-url flag with your own tunnel when starting your server.
Press p to open the app in your browser. This brings you to your development store's admin, where you can install your payments app.

Anchor to Push the configuration changes to your app and start your serverPush the configuration changes to your app and start your server

In a terminal, run the following commands to push the configuration changes to your app:

Deploy your app to update the config, which is defined in shopify.app.toml:
Terminal
shopify app deploy

Anchor to Explore payment sessionsExplore payment sessions

In this step, you'll explore the flows that an app needs to implement to process a payment.

In the app template, the endpoint that handles start payment session requests is predefined, and will automatically resolve or reject the payment by calling the Payments Apps API, based on the customer's name.

Note

The behavior of the endpoint that handles start payment session requests is exclusively for testing and should be replaced with your own payment processing logic in a production app.

Anchor to Start the payment sessionStart the payment session

When a customer selects your payment provider, Shopify sends an HTTP POST request to the payment session URL for the app. The request contains information about the customer and the order. To learn more about the request body and header, refer to the Credit Card payment request reference.

When the POST request is received, the payments app returns an HTTP 2xx response. This response is required for payment session creation to be considered successful.

If the request fails, then it's retried several times. If the request still fails, then the customer needs to retry their payment through Shopify checkout. If there's an error on the payments app's side, then return an appropriate error status code instead.

You configure the payment session URL for your app as part of the app extension configuration.

/app/routes/app.payment_session.jsx

import { createPaymentSession, getRejectReason } from "~/payments.repository";

import { sessionStorage } from "~/shopify.server";

import PaymentsAppsClient, { PAYMENT } from "~/payments-apps.graphql";

import { json } from "@remix-run/node";

import decryptCreditCardPayload from "~/encryption";

/**

* Saves and starts a payment session.

* Returns an empty response and process the payment asyncronously

export const action = async ({ request }) => {

const requestBody = await request.json();

const shopDomain = request.headers.get("shopify-shop-domain");

const sessionPayload = createParams(requestBody, shopDomain);

const paymentSession = await createPaymentSession(sessionPayload);

  if (!paymentSession) throw new Response("A PaymentSession couldn't be created.", { status: 500 });

  // Once the private key is set in encryption.js, this can be used for processing.

// const creditCard = decryptCard(sessionPayload.paymentMethod.data);

// Process the payment asyncronously

setTimeout((async () => { processPayment(paymentSession) }), 0);

// Return empty response, 201

return json({}, { status: 201 });

}

const createParams = ({id, gid, group, amount, currency, test, kind, customer, payment_method, proposed_at, cancel_url, client_details}, shopDomain) => (

{

id,

gid,

group,

amount,

currency,

test,

kind,

customer,

paymentMethod: payment_method,

proposedAt: proposed_at,

cancelUrl: cancel_url,

shop: shopDomain,

clientDetails: client_details,

}

)

const processPayment = async (paymentSession) => {

const session = (await sessionStorage.findSessionsByShop(paymentSession.shop))[0];

const client = new PaymentsAppsClient(session.shop, session.accessToken, PAYMENT);

const { billing_address: billingAddress, shipping_address: shippingAddress } = JSON.parse(paymentSession.customer);

const firstName = billingAddress.given_name || shippingAddress.given_name;

const lastName = (billingAddress.family_name || shippingAddress.family_name).toUpperCase();

// Last name can be used to simulate a rejection or a 3DS session (optionally frictionless)

if (firstName === "reject") {

await client.rejectSession(paymentSession, { reasonCode: getRejectReason(lastName) });

} else if (firstName === "pending") {

await client.pendSession(paymentSession);

} else if (firstName === "3ds") {

const redirectUrl = three_d_secure_redirect_url(paymentSession.id, lastName === "FRICTIONLESS");

await client.redirectSession(paymentSession, redirectUrl);

} else {

await client.resolveSession(paymentSession);

}

const three_d_secure_redirect_url = (payment_session_id, is_frictionless) => {

const url = process.env.SHOPIFY_APP_URL;

return `${url}/app/three-d-secure/${payment_session_id}${is_frictionless ? "?frictionless=true" : ""}`

}

const decryptCard = ({encrypted_message, ephemeral_public_key, tag}) => {

return decryptCreditCardPayload({

encryptedMessage: encrypted_message,

ephemeralPublicKey: ephemeral_public_key.replace(/\n$/, ""),

tag

})

}

Anchor to Sample payment session payload with localized fieldsSample payment session payload with localized fields

For certain countries that require additional fields on orders, localized_fields are included in the payload, inside the transaction_metadata object. For Brazil, localized_fields contains the CPF value. As a result of this, payment app developers don't need to manually add a CPF field to the payments app.

Note: Localized fields are available starting from API version 2024-07

Example transaction_metadata request parameters

"transaction_metadata": {

"localized_fields": [

{

"key": "shipping_credential",

"country_code": "BR",

"value": "06305371008"

}

]

Example payload

{

"id": "u0nwmSrNntjIWozmNslK5Tlq",

"gid": "gid://shopify/PaymentSession/u0nwmSrNntjIWozmNslK5Tlq",

"group": "rZNvy+1jH6Z+BcPqA5U5BSIcnUavBha3C63xBalm+xE=",

"session_id": "4B2dxmle3vGgimS4deUX3+2PgLF2+/0ZWnNsNSZcgdU=",

"amount": "123.00",

"currency": "CAD",

"test": false,

"merchant_locale": "en",

"payment_method": {

"type": "credit_card",

"data": {

"fingerprint": "65b1ae1fe49ff9d23d80e4967d9147e64b2357c0b2291f4a8bf719cbde331b4c",

"encrypted_message": "<ENCRYPTED_MESSAGE>",

"ephemeral_public_key": "<EPHEMERAL_PUBLIC_KEY>",

"tag": "TAG",

"moto": false

}

"proposed_at": "2023-06-23T17:03:36Z",

"customer": {

"billing_address": {

"given_name": "Alice",

"family_name": "Smith",

"line1": "Praça Visconde de Mauá",

"city": "Santos",

"postal_code": "11010-000",

"province": "São Paulo",

"country_code": "BR",

"phone_number": "5555555555",

"company": ""

"shipping_address": {

"given_name": "Alice",

"family_name": "Smith",

"line1": "Praça Visconde de Mauá",

"city": "Santos",

"postal_code": "11010-000",

"province": "São Paulo",

"country_code": "BR",

"phone_number": "5555555555",

"company": ""

"email": "buyer@example.com",

"phone_number": "5555555555",

"locale": "br"

"transaction_metadata": {

"localized_fields": [

{

"key": "shipping_credential",

"country_code": "BR",

"value": "06305371008"

}

]

"kind": "sale"

}

Anchor to Decrypt the credit card informationDecrypt the credit card information

The credit card information of the customer is encrypted using the ECIES hybrid encryption scheme, and passed during payment session creation as encrypted_message under payment_method.data. Credit card information is decrypted using the following steps:

Decode the Base64 encoded encrypted_message and tag.
Use fingerprint to identify the certificate that's used for encryption.
Compute the shared secret using the private key of the certificate and ephemeral_public_key.
Compute the hmac of the decoded encrypted_message and ensure it matches the decoded value of tag.
Decrypt the encrypted_message.

Caution

The application or service that decrypts the value of the encrypted_message must be in a PCI DSS compliant environment.

/app/encryption.js

import crypto from 'crypto';

import ecKeyUtils from 'eckey-utils';

const PRIVATE_KEY = '<PRIVATE_KEY_PEM>';

const EC_CURVE = 'prime256v1';

const CIPHER = 'aes-256-ctr';

const CIPHER_LENGTH = crypto.getCipherInfo(CIPHER)?.keyLength || 0;

const MAC_DIGEST = 'sha256';

const MAC_LENGTH = crypto.createHash(MAC_DIGEST).digest().length / 2;

/**

* Decrypts ECIES credit card payload from Shopify

* @param {*} encryptedPayload

const decryptCreditCardPayload = ({ encryptedMessage, ephemeralPublicKey, tag }) => {

console.log('[ECIES] Beginning decryption...');

const ciphertext = decodeBase64(encryptedMessage);

const mac = decodeBase64(tag);

const sharedSecret = computeSharedSecret(ephemeralPublicKey);

  const keyPair = crypto.hkdfSync(MAC_DIGEST, sharedSecret, '', '', CIPHER_LENGTH + MAC_LENGTH);

const cipherKey = Buffer.from(keyPair.slice(0, CIPHER_LENGTH));

const computedMac = computeMac(keyPair, ciphertext);

  if (!crypto.timingSafeEqual(computedMac, mac)) throw new Error('Invalid Message Authenticaton Code');

const result = decryptCipher(cipherKey, ciphertext);

console.log(`[ECIES] Decryption complete.`);

return JSON.parse(result);

}

// Decode a base64 encoded string

const decodeBase64 = (encoded) => {

return Buffer.from(encoded, 'base64');

}

// Compute the shared secret using the `ephemeralPublicKey`

const computeSharedSecret = (ephemeralPublicKey) => {

console.log('[ECIES] Creating keys...');

const ecdh = crypto.createECDH(EC_CURVE);

const privateKey = ecKeyUtils.parsePem(PRIVATE_KEY).privateKey;

ecdh.setPrivateKey(privateKey);

const publicKey = ecKeyUtils.parsePem(ephemeralPublicKey).publicKey;

return ecdh.computeSecret(publicKey);

}

// Compute the hmac of decoded `encryptedMessage` to ensure it matches the decoded value of `tag`

const computeMac = (keyPair, ciphertext) => {

console.log('[ECIES] Computing HMAC...');

  const hmacKey = Buffer.from(keyPair.slice(CIPHER_LENGTH, MAC_LENGTH + CIPHER_LENGTH));

const hmac = crypto.createHmac(MAC_DIGEST, hmacKey);

hmac.update(ciphertext);

return hmac.digest().subarray(0, MAC_LENGTH);

}

// Decrypt the ciphertext using the key

const decryptCipher = (cipherKey, ciphertext) => {

console.log('[ECIES] Decrypting...');

const iv = Buffer.alloc(16, 0);

const decipher = crypto.createCipheriv(CIPHER, cipherKey, iv);

  return decipher.update(ciphertext.toString('hex'), 'hex', 'utf8') + decipher.final('utf8');

}

export default decryptCreditCardPayload;

Anchor to Resolve a paymentResolve a payment

Payments apps use the paymentSessionResolve mutation after the customer has successfully gone through the payment process to complete the payment. The id argument corresponds to the global identifier (gid) of the payment.

Note

The authorizationExpiresAt argument must be provided if the payment session request kind is authorization.
The PaymentSessionThreeDSecureAuthentication argument must be provided if the paymentSessionRedirect mutation has been called for 3-D Secure and successfully executed without returning userErrors.
You must provide the networkTransactionId argument, if available. The argument identifies the transaction on the payment network and improves authorization rates on subsequent transactions.

In the referenced code, this.resolveMutation corresponds to the paymentSessionResolve mutation.

paymentSessionResolve

PaymentSessionThreeDSecureAuthentication

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Reject a paymentReject a payment

The payments app should reject a payment if the customer can't complete a payment with the provider. The rejected payment tells Shopify that the checkout process will be halted. For example, if you don't want to process a high-risk payment, then you can reject the payment using the paymentSessionReject mutation.

Note

The PaymentSessionThreeDSecureAuthentication argument must be provided if the paymentSessionRedirect mutation has been called for 3-D Secure and successfully executed without returning userErrors.

In the referenced code, this.rejectMutation corresponds to the paymentSessionReject mutation.

paymentSessionReject

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Triggering resolve, or reject a payment in the templateTriggering resolve, or reject a payment in the template

In the app template, after a start payment session request has been received by the app, the payment is automatically resolved or rejected based on the customer's name.

If the customer's first name is reject, then the payment is rejected. Otherwise, the payment is resolved.

/app/routes/app.payment_session.jsx

import { createPaymentSession, getRejectReason } from "~/payments.repository";

import { sessionStorage } from "~/shopify.server";

import PaymentsAppsClient, { PAYMENT } from "~/payments-apps.graphql";

import { json } from "@remix-run/node";

import decryptCreditCardPayload from "~/encryption";

/**

* Saves and starts a payment session.

* Returns an empty response and process the payment asyncronously

export const action = async ({ request }) => {

const requestBody = await request.json();

const shopDomain = request.headers.get("shopify-shop-domain");

const sessionPayload = createParams(requestBody, shopDomain);

const paymentSession = await createPaymentSession(sessionPayload);

if (!paymentSession) throw new Response("A PaymentSession couldn't be created.", { status: 500 });

// Once the private key is set in encryption.js, this can be used for processing.

// const creditCard = decryptCard(sessionPayload.paymentMethod.data);

// Process the payment asyncronously

setTimeout((async () => { processPayment(paymentSession) }), 0);

// Return empty response, 201

return json({}, { status: 201 });

}

const createParams = ({id, gid, group, amount, currency, test, kind, customer, payment_method, proposed_at, cancel_url, client_details}, shopDomain) => (

{

id,

gid,

group,

amount,

currency,

test,

kind,

customer,

paymentMethod: payment_method,

proposedAt: proposed_at,

cancelUrl: cancel_url,

shop: shopDomain,

clientDetails: client_details,

}

)

const processPayment = async (paymentSession) => {

  const session = (await sessionStorage.findSessionsByShop(paymentSession.shop))[0];

  const client = new PaymentsAppsClient(session.shop, session.accessToken, PAYMENT);

  const { billing_address: billingAddress, shipping_address: shippingAddress } = JSON.parse(paymentSession.customer);

const firstName = billingAddress.given_name || shippingAddress.given_name;

  const lastName = (billingAddress.family_name || shippingAddress.family_name).toUpperCase();

  // Last name can be used to simulate a rejection or a 3DS session (optionally frictionless)

if (firstName === "reject") {

    await client.rejectSession(paymentSession, { reasonCode: getRejectReason(lastName) });

} else if (firstName === "pending") {

await client.pendSession(paymentSession);

} else if (firstName === "3ds") {

    const redirectUrl = three_d_secure_redirect_url(paymentSession.id, lastName === "FRICTIONLESS");

await client.redirectSession(paymentSession, redirectUrl);

} else {

await client.resolveSession(paymentSession);

}

const three_d_secure_redirect_url = (payment_session_id, is_frictionless) => {

const url = process.env.SHOPIFY_APP_URL;

return `${url}/app/three-d-secure/${payment_session_id}${is_frictionless ? "?frictionless=true" : ""}`

}

const decryptCard = ({encrypted_message, ephemeral_public_key, tag}) => {

return decryptCreditCardPayload({

encryptedMessage: encrypted_message,

ephemeralPublicKey: ephemeral_public_key.replace(/\n$/, ""),

tag

})

}

Anchor to TimeoutTimeout

Credit card payment apps are expected to process payments in a few seconds. To ensure a good customer experience, the customer is redirected to the order confirmation page when a payment times out. However, the order status is automatically set to Pending in the Shopify admin. You should still finalize the payment by calling the paymentSessionResolve or paymentSessionReject mutations.

Anchor to Supporting 3-D SecureSupporting 3-D Secure

If you add support for 3-D Secure to your payments app, then it requires some additional configuration and logic prior to resolving or rejecting the payment.

Anchor to Redirect the customerRedirect the customer

After the payments app determines that it needs to perform a 3-D Secure (3DS) authentication, and after the app returns a response to HTTP POST request sent from Shopify to initiate the payment flow, the app should use the paymentSessionRedirect mutation to provide to the URL where 3DS authentication will take place. Shopify renders the URL provided by the app in an iframe in the customer's browser.

The paymentSessionRedirect mutation request must be received by Shopify within a given timeout. After the timeout, Shopify redirects the customer back to Shopify's checkout, and will fail any additional paymentSessionRedirect mutations with the BUYER_ALREADY_REDIRECTED_BY_SHOPIFY error code.

The id argument corresponds to the global identifier (gid) of the payment.

To defend against clickjacking, Shopify sets the source of the frame-ancestors directive in the Content-Security-Policy header to 'none'. This prevents any domain from framing the page containing the iframe where Shopify renders the URL provided by the app.

In the referenced code, this.redirectMutation corresponds to the paymentSessionRedirect mutation.

paymentSessionRedirect

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Triggering 3-D Secure in the templateTriggering 3-D Secure in the template

In the app template, 3-D Secure is initiated when the customer's first name is 3ds. The app template redirects the customer to the 3-D Secure simulator.

In a production app, you would redirect the customer to your own 3-D Secure authentication page.

/app/routes/app.payment_session.jsx

import { createPaymentSession, getRejectReason } from "~/payments.repository";

import { sessionStorage } from "~/shopify.server";

import PaymentsAppsClient, { PAYMENT } from "~/payments-apps.graphql";

import { json } from "@remix-run/node";

import decryptCreditCardPayload from "~/encryption";

/**

* Saves and starts a payment session.

* Returns an empty response and process the payment asyncronously

export const action = async ({ request }) => {

const requestBody = await request.json();

const shopDomain = request.headers.get("shopify-shop-domain");

const sessionPayload = createParams(requestBody, shopDomain);

const paymentSession = await createPaymentSession(sessionPayload);

if (!paymentSession) throw new Response("A PaymentSession couldn't be created.", { status: 500 });

// Once the private key is set in encryption.js, this can be used for processing.

// const creditCard = decryptCard(sessionPayload.paymentMethod.data);

// Process the payment asyncronously

setTimeout((async () => { processPayment(paymentSession) }), 0);

// Return empty response, 201

return json({}, { status: 201 });

}

const createParams = ({id, gid, group, amount, currency, test, kind, customer, payment_method, proposed_at, cancel_url, client_details}, shopDomain) => (

{

id,

gid,

group,

amount,

currency,

test,

kind,

customer,

paymentMethod: payment_method,

proposedAt: proposed_at,

cancelUrl: cancel_url,

shop: shopDomain,

clientDetails: client_details,

}

)

const processPayment = async (paymentSession) => {

const session = (await sessionStorage.findSessionsByShop(paymentSession.shop))[0];

const client = new PaymentsAppsClient(session.shop, session.accessToken, PAYMENT);

const { billing_address: billingAddress, shipping_address: shippingAddress } = JSON.parse(paymentSession.customer);

const firstName = billingAddress.given_name || shippingAddress.given_name;

const lastName = (billingAddress.family_name || shippingAddress.family_name).toUpperCase();

// Last name can be used to simulate a rejection or a 3DS session (optionally frictionless)

if (firstName === "reject") {

await client.rejectSession(paymentSession, { reasonCode: getRejectReason(lastName) });

} else if (firstName === "pending") {

await client.pendSession(paymentSession);

} else if (firstName === "3ds") {

    const redirectUrl = three_d_secure_redirect_url(paymentSession.id, lastName === "FRICTIONLESS");

await client.redirectSession(paymentSession, redirectUrl);

} else {

await client.resolveSession(paymentSession);

}

const three_d_secure_redirect_url = (payment_session_id, is_frictionless) => {

const url = process.env.SHOPIFY_APP_URL;

  return `${url}/app/three-d-secure/${payment_session_id}${is_frictionless ? "?frictionless=true" : ""}`

}

const decryptCard = ({encrypted_message, ephemeral_public_key, tag}) => {

return decryptCreditCardPayload({

encryptedMessage: encrypted_message,

ephemeralPublicKey: ephemeral_public_key.replace(/\n$/, ""),

tag

})

}

Anchor to Confirm a paymentConfirm a payment

You must use the paymentSessionConfirm mutation to confirm with Shopify whether to proceed with the payment request, according to Shopify's business logic. For example, Shopify checks that products aren't oversold and that discount codes are still valid. If you perform a 3-D Secure challenge, then this mutation should be run after the challenge is performed.

The id argument corresponds to the global identifier (gid) of the payment.

In the referenced code, this.confirmMutation corresponds to the paymentSessionConfirm mutation.

paymentSessionConfirm

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Triggering a payment confirmation in the templateTriggering a payment confirmation in the template

In the app template, the 3-D Secure simulator confirms the payment after the user chooses whether to complete the challenge successfully or with an error.

In a production app, you would confirm the payment after the customer completes the 3-D Secure challenge, based on the result of the challenge.

/app/routes/app.three-d-secure.$paymentId.jsx

import {

Button,

Card,

FooterHelp,

FormLayout,

Layout,

Page,

Text,

TextField,

BlockStack,

Link,

Banner,

Select,

LegacyStack,

ChoiceList,

} from "@shopify/polaris";

import { useCallback, useEffect, useState } from "react";

import {

Form,

useActionData,

} from "@remix-run/react";

import { json, redirect } from "@remix-run/node";

import { sessionStorage } from "../shopify.server";

import { getPaymentSession, updatePaymentSessionAuthData, rejectReasons } from "~/payments.repository";

import PaymentsAppsClient, { PAYMENT } from "~/payments-apps.graphql";

import ThreeDSecure from "~/three-d-s.constants";

/**

* Loads the payment session for 3DS.

export const loader = async ({request, params: { paymentId } }) => {

const paymentSession = await getPaymentSession(paymentId);

const url = new URL(request.url);

const frictionless = url.searchParams.get("frictionless") === 'true';

Anchor to Process a confirm sessionProcess a confirm session

Following paymentSessionConfirm, when Shopify determines that the payment request can proceed based on its business logic, Shopify sends a POST request to the confirm session URL of the credit card payments app extension, delivering the confirmation result.

Shopify must receive an HTTP 200 or 201 response for the payment session confirmation to be successful.

If the request fails, then it's retried several times. If the request still fails, then the customer needs to retry their payment through Shopify checkout.

If there's an error on the payments app's side, then don't respond with an HTTP 2xx. Use an appropriate error status code instead.

At this point, your app can begin processing the payment, and can call either of paymentSessionResolve or paymentSessionReject to resolve or reject the payment respectively.

When Shopify indicates that the payment request can't proceed, the payments app must invoke the paymentSessionReject mutation using the CONFIRMATION_REJECTED reason code.

The app template is set up to store and automatically resolve or reject a payment session based on either the 3-D Secure challenge's result or the customer's last name when a confirm request is sent from Shopify to the app. Your app should replace this logic with its own post-confirmation processing logic.

paymentSessionResolve

paymentSessionReject

CONFIRMATION_REJECTED

/app/routes/app.confirm_session.jsx

import { json } from "@remix-run/node";

import PaymentsAppsClient, { PAYMENT } from "~/payments-apps.graphql";

import { getPaymentSession, getRejectReason, rejectReasons } from "~/payments.repository";

import { sessionStorage } from "../shopify.server";

/**

* Confirms a session.

export const action = async ({ request }) => {

const requestBody = await request.json();

const paymentSession = await getPaymentSession(requestBody.id);

  const lastName = JSON.parse(paymentSession.customer).billing_address.family_name

  const partnerError = JSON.parse(paymentSession["threeDSecureAuthentication"])['partnerError']

  const session = (await sessionStorage.findSessionsByShop(paymentSession.shop))[0];

  const client = new PaymentsAppsClient(session.shop, session.accessToken, PAYMENT);

let response;

// Last name can be used to simulate a rejection

if (rejectReasons.includes(lastName) || partnerError) {

    response = await client.rejectSession(paymentSession, { reasonCode: getRejectReason(lastName) });

    return json({ errors: [`Something went wrong. Error code: ${lastName}`] }, { status: response.status });

}

response = await client.resolveSession(paymentSession);

const userErrors = response.userErrors;

  if (userErrors?.length > 0) return json({ errors: userErrors }, { status: response.status });

return json({}, { status: 200 });

}

Anchor to Explore refund sessionsExplore refund sessions

In this step, you'll explore the flows that an app needs to implement to process a refund.

In the app template, the endpoint that handles start refund session requests is predefined to store sessions for an asynchronous resolution.

Anchor to Start the refund sessionStart the refund session

The refund flow begins with an HTTP POST request sent from Shopify to the payments app's refund session URL. Shopify must receive an HTTP 201 (Created) response for the refund session creation to be successful.

If the request fails, then it's retried several times. If the request still fails, then the user needs to manually retry the refund in the Shopify admin.

You configure the refund session URL for your app as part of the app extension configuration.

/app/routes/app.refund_session.jsx

import { json } from "@remix-run/node";

import { createRefundSession } from "~/payments.repository";

/**

* Saves and starts a refund session.

export const action = async ({ request }) => {

const requestBody = await request.json();

const refundSessionHash = createParams(requestBody);

const refundSession = await createRefundSession(refundSessionHash);

  if (!refundSession) throw new Response("A RefundSession couldn't be created.", { status: 500 });

return json(refundSessionHash);

}

const createParams = ({id, gid, amount, currency, payment_id, proposed_at}) => (

{

id,

gid,

amount,

currency,

paymentId: payment_id,

proposedAt: proposed_at,

}

)

Anchor to Resolve a refundResolve a refund

After the app has successfully processed the refund request, it's resolved by using the refundSessionResolve mutation. The id argument corresponds to the gid of the refund.

In the referenced code, this.resolveMutation corresponds to the refundSessionResolve mutation.

refundSessionResolve

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Reject a refundReject a refund

If the app can't process a refund, then it needs to reject it. You should only reject a refund in the case of final and irrecoverable errors. Otherwise, you can attempt to process the refund again.

The refund is rejected using the refundSessionReject mutation.

As part of the rejection, a reason why the refund was rejected must be included as part of RefundSessionRejectionReasonInput.

The RefundSessionRejectionReasonInput.code is a RefundSessionStatusReasonRejectionCode, which is an enum of standardized error codes.

The RefundSessionRejectionReasonInput.merchantMessage argument is a localized error message presented to the merchant explaining why the refund was rejected.

In the referenced code, this.rejectMutation corresponds to the refundSessionReject mutation.

refundSessionReject

RefundSessionRejectionReasonInput

RefundSessionStatusReasonRejectionCode

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Triggering resolve or reject for a refund in the templateTriggering resolve or reject for a refund in the template

In the app template, the simulator built into the dashboard handles the resolution or rejection of all post-payment sessions, including refunds, asynchronously. This means that after a refund is created in a store's Shopify admin, it must be manually completed from the app template's dashboard.

In a production-ready app, your app would process the refund itself once it receives the start refund session request.

/app/routes/app.dashboard_simulator.$paymentId.jsx

import {

Button,

Card,

Layout,

Page,

Text,

Banner,

DescriptionList,

InlineCode,

Link,

Icon,

LegacyStack,

DataTable,

Modal,

} from "@shopify/polaris";

import { XSmallIcon, CheckSmallIcon } from "@shopify/polaris-icons";

import { useState, useCallback, useEffect } from "react";

import {

useActionData,

useLoaderData,

useSubmit

} from "@remix-run/react";

import { json } from "@remix-run/node";

import { sessionStorage } from "../shopify.server";

import {getPaymentSession, PENDING} from "~/payments.repository";

import PaymentsAppsClient, { PAYMENT, REFUND, CAPTURE, VOID } from "~/payments-apps.graphql";

/**

* Loads in the relevant payment session along with it's related refund, capture, and void sessions.

export const loader = async ({ params: { paymentId } }) => {

const paymentSession = await getPaymentSession(paymentId);

return json({

paymentSession,

Anchor to Explore capture sessionsExplore capture sessions

A capture describes the process of how merchants capture funds for an authorized payment. A capture is the next step of the payment flow, and occurs after an authorized payment is finalized. Finalized payments have kind set to authorization.

Anchor to Start the capture sessionStart the capture session

A capture can only be performed when the payment initiated by Shopify has a kind property with a value of authorization. With an authorization, the app places a hold on funds and then replies to Shopify's capture request.

The capture flow begins with an HTTP POST request sent from Shopify to the payments app's capture session URL.

You configure the capture session URL for your app as part of the app extension configuration.

Shopify sends a capture request to the payments app after a merchant tries to capture the funds on an authorized transaction. When this occurs, the app template is set up to store a capture session. These sessions can then be resolved through the simulator for testing. In a production-ready app, this is when your app would process the capture request.

/app/routes/app.capture_session.jsx

import { json } from "@remix-run/node";

import { createCaptureSession } from "~/payments.repository";

/**

* Saves and starts a capture session.

export const action = async ({ request }) => {

const requestBody = await request.json();

const captureSessionHash = createParams(requestBody);

const captureSession = await createCaptureSession(captureSessionHash);

  if (!captureSession) throw new Response("A CaptureSession couldn't be created.", { status: 500 });

return json(captureSessionHash);

}

const createParams = ({id, gid, amount, currency, payment_id, proposed_at}) => (

{

id,

gid,

amount,

currency,

paymentId: payment_id,

proposedAt: proposed_at,

}

)

Anchor to Resolve a capture sessionResolve a capture session

After the app has successfully processed the capture request from Shopify, it's resolved using the captureSessionResolve mutation.

In the referenced code, this.resolveMutation corresponds to the captureSessionResolve mutation.

captureSessionResolve

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Reject a captureReject a capture

If you don't want to process a capture request, then you should reject it. You might want to reject a capture if authorization has expired or if you suspect that the request is fraudulent or high risk. You should only reject a capture in the case of final and irrecoverable errors. Otherwise, you should re-attempt to resolve the capture.

The app rejects a capture using the captureSessionReject mutation.

As part of the rejection, you need to include a reason why the capture was rejected as part of CaptureSessionRejectionReasonInput.

The CaptureSessionRejectionReasonInput.code is a CaptureSessionStatusReasonRejectionCode, which is an enum of standardized error codes.

The CaptureSessionRejectionReasonInput.merchantMessage argument is a localized error message presented to the merchant explaining why the capture was rejected.

In the referenced code, this.rejectMutation corresponds to the captureSessionReject mutation.

captureSessionReject

CaptureSessionRejectionReasonInput

CaptureSessionStatusReasonRejectionCode

/app/payments-apps.graphql.js

import schema from "./payments-apps.schema";

import {

updatePaymentSessionStatus,

updateRefundSessionStatus,

updateCaptureSessionStatus,

updateVoidSessionStatus,

RESOLVE,

REJECT,

PENDING

} from "./payments.repository";

/**

* Client to interface with the Payments Apps GraphQL API.

* paymentsAppConfigure: Configure the payments app with the provided variables.

* paymentSessionResolve: Resolves the given payment session.

* paymentSessionReject: Rejects the given payment session.

* refundSessionResolve: Resolves the given refund session.

* refundSessionReject: Rejects the given refund session.

export default class PaymentsAppsClient {

constructor(shop, accessToken, type) {

this.shop = shop;

this.type = type || PAYMENT; // default

this.accessToken = accessToken;

this.resolveMutation = "";

this.rejectMutation = "";

this.pendingMutation = "";

this.redirectMutation = "";

this.confirmMutation = "";

this.dependencyInjector(type);

const tomorrow = new Date();

tomorrow.setDate(tomorrow.getDate() + 1);

this.tomorrow = tomorrow;

Anchor to Triggering resolve or reject for a capture in the templateTriggering resolve or reject for a capture in the template

In the app template, the simulator built into the dashboard (/app/dashboard) handles the resolution or rejection of all post-payment sessions, including captures, asynchronously. This means that after a capture is created in a store's Shopify admin, it must be manually completed from the app template's dashboard.

In a production-ready app, your app would process the capture itself after it receives the start capture session request.

/app/routes/app.dashboard_simulator.$paymentId.jsx

import {

Button,

Card,

Layout,

Page,

Text,

Banner,

DescriptionList,

InlineCode,

Link,

Icon,

LegacyStack,

DataTable,

Modal,

} from "@shopify/polaris";

import { XSmallIcon, CheckSmallIcon } from "@shopify/polaris-icons";

import { useState, useCallback, useEffect } from "react";

import {

useActionData,

useLoaderData,

useSubmit

} from "@remix-run/react";

import { json } from "@remix-run/node";

import { sessionStorage } from "../shopify.server";

import {getPaymentSession, PENDING} from "~/payments.repository";

import PaymentsAppsClient, { PAYMENT, REFUND, CAPTURE, VOID } from "~/payments-apps.graphql";

/**

* Loads in the relevant payment session along with it's related refund, capture, and void sessions.

export const loader = async ({ params: { paymentId } }) => {

const paymentSession = await getPaymentSession(paymentId);

return json({

paymentSession,

Anchor to Explore void sessionsExplore void sessions

A void describes the process of how merchants void funds for an authorized payment. A void is the next step of the payment flow, and occurs after an authorized payment is finalized. Finalized payments have kind set to authorization.

Anchor to Start the void sessionStart the void session

A void can only be performed when the payment initiated by Shopify has a kind property with a value of authorization.

The void flow begins with an HTTP POST request sent from Shopify to the payments app's void session URL.

You configure the void session URL for your app as part of the app extension configuration.

The app template stores the void session when Shopify sends a void request to a payments app after a merchant tries to cancel the order for an authorized transaction. These sessions can then be resolved through the simulator for testing. In a production-ready app, this is when your app would process the void request.

/app/routes/app.void_session.jsx

import { json } from "@remix-run/node";

import { createVoidSession } from "~/payments.repository";

/**

* Saves and starts a void session.

export const action = async ({ request }) => {

const requestBody = await request.json();

const voidSessionHash = createParams(requestBody);

const voidSession = await createVoidSession(voidSessionHash);

  if (!voidSession) throw new Response("A VoidSession couldn't be created.", { status: 500 });

return json(voidSessionHash);

}

const createParams = ({id, gid, payment_id, proposed_at}) => (

{

id,

gid,

paymentId: payment_id,

proposedAt: proposed_at,

}

)

Anchor to Resolve a void sessionResolve a void session

After the app has successfully processed the void request, it is resolved using the voidSessionResolve mutation.

voidSessionResolve

/app/payments-apps.schema.js

/**

* This "schema" contains the mutations consumed by the client in payments-apps.graphql

const paymentsAppConfigure = `

mutation PaymentsAppConfigure($externalHandle: String, $ready: Boolean!) {

paymentsAppConfigure(externalHandle: $externalHandle, ready: $ready) {

userErrors{

field

message

}

const paymentSessionResolve = `

mutation PaymentSessionResolve(

$id: ID!,

$authorizationExpiresAt: DateTime,

$authentication: PaymentSessionThreeDSecureAuthentication,

$networkTransactionId: String

) {

paymentSessionResolve(

id: $id,

authorizationExpiresAt: $authorizationExpiresAt,

authentication: $authentication,

networkTransactionId: $networkTransactionId

) {

paymentSession {

state {

... on PaymentSessionStateResolved {

code

}

userErrors {

Anchor to Reject a voidReject a void

If your app can't process a void request, then you should reject it. You should only reject a void in the case of final and irrecoverable errors. Otherwise, you can attempt to resolve the void again.

You can reject a void using the voidSessionReject mutation.

As part of the rejection, you need to include a reason why the void was rejected as part of VoidSessionRejectionReasonInput.

The VoidSessionRejectionReasonInput.code is a VoidSessionStatusReasonRejectionCode, which is an enum of standardized error codes.

The VoidSessionRejectionReasonInput.merchantMessage argument is a localized error message presented to the merchant explaining why the void was rejected.

voidSessionReject

VoidSessionRejectionReasonInput

VoidSessionStatusReasonRejectionCode

/app/payments-apps.schema.js

/**

* This "schema" contains the mutations consumed by the client in payments-apps.graphql

const paymentsAppConfigure = `

mutation PaymentsAppConfigure($externalHandle: String, $ready: Boolean!) {

paymentsAppConfigure(externalHandle: $externalHandle, ready: $ready) {

userErrors{

field

message

}

const paymentSessionResolve = `

mutation PaymentSessionResolve(

$id: ID!,

$authorizationExpiresAt: DateTime,

$authentication: PaymentSessionThreeDSecureAuthentication,

$networkTransactionId: String

) {

paymentSessionResolve(

id: $id,

authorizationExpiresAt: $authorizationExpiresAt,

authentication: $authentication,

networkTransactionId: $networkTransactionId

) {

paymentSession {

state {

... on PaymentSessionStateResolved {

code

}

userErrors {

Anchor to Triggering resolve or reject for a void in the templateTriggering resolve or reject for a void in the template

In the app template, the simulator built into the dashboard handles the resolution or rejection of all post-payment sessions, including voids, asynchronously. This means that after a void is created in a store's Shopify admin, it must be manually completed from the app template's dashboard.

In a production-ready app, your app would process the void itself after it receives the start void session request.

/app/routes/app.dashboard_simulator.$paymentId.jsx

import {

Button,

Card,

Layout,

Page,

Text,

Banner,

DescriptionList,

InlineCode,

Link,

Icon,

LegacyStack,

DataTable,

Modal,

} from "@shopify/polaris";

import { XSmallIcon, CheckSmallIcon } from "@shopify/polaris-icons";

import { useState, useCallback, useEffect } from "react";

import {

useActionData,

useLoaderData,

useSubmit

} from "@remix-run/react";

import { json } from "@remix-run/node";

import { sessionStorage } from "../shopify.server";

import {getPaymentSession, PENDING} from "~/payments.repository";

import PaymentsAppsClient, { PAYMENT, REFUND, CAPTURE, VOID } from "~/payments-apps.graphql";

/**

* Loads in the relevant payment session along with it's related refund, capture, and void sessions.

export const loader = async ({ params: { paymentId } }) => {

const paymentSession = await getPaymentSession(paymentId);

return json({

paymentSession,

Anchor to Test your payments extension locallyTest your payments extension locally

You should test that your various endpoints work as expected locally.

Anchor to Submit a request to your local serverSubmit a request to your local server

With the dev server you started previously, go through the relevant requests from our reference, and submit a request to your app with cURL or an API platform like Postman or Insomnia.

Anchor to Deploy new versions of your payments extensionDeploy new versions of your payments extension

Anchor to Deploy and release your extensionDeploy and release your extension

Create and release an app version.

Navigate to your app directory.
Run the following command.

Optionally, you can provide a name or message for the version using the --version and --message flags.

Terminal

shopify app deploy

An app version created using Shopify CLI contains the following:

The app configuration from the local configuration file. If the include_config_on_deploy flag is not set or false, then the configuration from the active app version will be used instead.
The local version of the app's CLI-managed extensions. If you have an extension in your deployed app, but the extension code doesn't exist locally, then the extension isn't included in your app version.

Releasing an app version replaces the current active version that's served to stores with your app installed. It might take several minutes for app users to be upgraded to the new version.

Note

If you want to create a version, but want to avoid releasing it to users, then run the deploy command with a --no-release flag.

You can release the unreleased app version using Shopify CLI's release command, or through the Partner Dashboard.

Anchor to Preview payment extensions on a development storePreview payment extensions on a development store

To test changes to your payments extension on a development store without submitting it for approval after the initial version is approved, you can use Shopify CLI's dev command. This helps bypass the approval process for various extension versions during development.

In a terminal, navigate to your app directory.
Start your server to build and preview your app:

Terminal
shopify app dev
Press p to preview the app in your browser on the development store selected.

Terminal
› Press d │ toggle development store preview: ✔ on
› Press g │ open GraphiQL (Admin API) in your browser
› Press p │ preview in your browser
› Press q │ quit
Proceed with testing the extension config changes in Shopify Admin or on checkout in a new browser session.
Keep the CLI running to see your local configuration changes reflect online on your development store.

Anchor to Test your payments app with a ShopTest your payments app with a Shop

Preview your app to make sure that it works as expected with Shopify.

Info

The testing steps outlined in this section are specific to apps built with the template. The template provides a basic UI that lets you test the payment flows, but your app might have a UI stored outside of the admin.

Anchor to Start your serverStart your server

If you're using a permanent tunnel with your app extension, you can use the Shopify CLI dev command to build your app and preview it on your development store.

Otherwise, deploy your app to your server, and move to the next step.

In a terminal, navigate to your app directory.
Either start or restart your server to build and preview your app:

Terminal
shopify app dev --tunnel-url <tunnel>
Press p to open the developer console.
In the developer console page, click on the preview link for the app.

Anchor to Install and test the payments appInstall and test the payments app

Follow these steps to test the payments app flows:

From the app splash page, enter an account name.
Select Ready > Unstable and click Submit.
In the banner, click Return to Shopify.
Enable test mode.
Click Activate.
You can select Resolve to complete the payment, or Reject to cancel and go back.

Anchor to Set up your payments app to accept test paymentsSet up your payments app to accept test payments

Onboard your app onto your development store.

In the Shopify admin for your development store, go to Settings > Apps and sales channels.
Select your payments app, then click Open app. The app home opens in a new window.
This step is applicable only to the template, if you've implemented the app yourself, complete your onboarding steps, and skip to the next step.

From the app home, enter an account name, select Ready? and your Payments Apps API API Version, and then click Submit.

In the banner, click Return to Shopify.

You'll return to admin, where you can review the app's details prior to activation.

Troubleshooting
Anchor to An error ocurred while onboarding your appAn error ocurred while onboarding your app
Your app extension may not be set up properly. Ensure the URLs provided are accurate, and that the app extension is released. After this, you might have to uninstall and reinstall your payments app to successfully onboard. You can uninstall from your app's admin under Settings > Apps and sales channels, and reinstall from your app's page in the Partner dashboard, under Test your app.
Enable test mode.
Click Activate.

Now that your app is installed, you can test payments, refunds, captures, voids, and 3-D Secure, if enabled.

Payments Apps API

Troubleshooting

Anchor to An error ocurred while onboarding your appAn error ocurred while onboarding your app

You might have to uninstall and reinstall your payments app. You can uninstall from your app's admin under Settings > Apps and sales channels, and reinstall from your app's page in the Partner dashboard, under Test your app.

Anchor to Test paymentsTest payments

Make a payment, and create an order.

In your development store, add a product to your cart, and then begin a checkout.
Complete the checkout as usual, until the Payment section.

At this point, your payments app should be available under the Credit card section.
Enter some test credit card details, and then select Pay now.

Shopify sends a request to the payment session URL specified in your app extension configuration.

Your app should then begin, and complete processing the payment.
Verify the payment is complete by finding the order under Orders in your shop's admin.

Anchor to Test refundsTest refunds

Make a refund on an order.

In the Shopify admin for your development store, go to Orders. Select an order with a completed payment.
In the top right corner, click Refund.
Select the item to refund, and then click Refund <amount>.

Shopify sends a request to the refund session URL specified in your app extension configuration.

If you've customized your app, then the refund process should trigger.

If you're testing the app template, then your app receives this request, and saves a record of it. Perform the following additional steps:

Navigate to /app/dashboard in your app to find the relevant payment session. From the app home, you can click Dashboard.
Click Simulate, and then scroll down to Refunds. On the relevant refund session, click Open.
Select Resolve or Reject to complete the refund.
Verify that the refund has completed by returning to the order under Orders in your store's admin. You should see that the order is now marked as Refunded.

Anchor to Test capturesTest captures

Capture funds from an authorized payment.

In your development store, enable manual payment capture to test captures.
Submit another test payment.

The order appears in the Shopify admin under Orders.
Open the new order. In the top right corner, click Capture payment.
In the page that opens, click Accept <amount>.

Shopify sends a request to the capture session URL specified in your app extension configuration.

If you've customized your app, then the capture process should trigger.

If you're testing the app template, then your app receives this request, and saves a record of it. Perform the following additional steps:

Navigate to /app/dashboard in your app to find the relevant payment session. From the app home, you can click Dashboard.
Click Simulate, and then scroll down to Captures. On the relevant capture session, click Open.
Select Resolve or Reject to complete the capture.
Verify that the capture has completed by returning to the order under Orders in your store's admin. You should see that the order is now marked as Paid.

Anchor to Test voidsTest voids

Void an authorized payment.

In your development store, enable manual payment capture to test voids.
Submit another test payment.

The order appears in the Shopify admin under Orders.
Open the new order. In the top right, click More actions, then Cancel order. In the modal that opens, click Cancel order.

Shopify sends a request to the void session URL specified in your app extension configuration.

If you've customized your app, then the void process should trigger.

If you're testing the app template, then your app receives this request, and saves a record of it. Perform the following additional steps:

Navigate to /app/dashboard in your app to find the relevant payment session. From the app home, you can click Dashboard.
Click Simulate, and then scroll down to Void. Click Open on the void session.
Select Resolve or Reject to complete the void.
Verify that the void has completed by returning to the order under Orders in your store's admin. You should see that the order is now marked as Voided.

Anchor to Test 3-D SecureTest 3-D Secure

Complete a 3-D Secure challenge.

In your development store, add a product to your cart, and begin a checkout.
Complete the checkout as usual. If you're using the template, you can initiate the 3-D Secure flow by setting your first name to 3ds.

If you want to try out the frictionless 3-D Secure experience offered by the template, you can enter the last name as frictionless during checkout.
When you reach the Payment section, your payments app should be available under the Credit card section.
Enter some test credit card details, and then select Pay now.

Shopify sends a request to the payment session URL specified in your app extension configuration. Your app should make a paymentSessionRedirect request at this point, which Shopify will respond to by opening an iframe in checkout with the provided URL.
The URL specified in your paymentSessionRedirect request is displayed in an iframe. In the template, you can select either Authentication Data or Partner Error and click Submit.

Your app should then send a paymentSessionConfirm request with the result of the 3-D Secure challenge. Shopify will respond with a request to the confirm session URL specified in your app extension configuration.
If the confirmation result is successful, then your app should begin, and then complete processing the payment. You can verify the payment is complete by finding the order under Orders in the Shopify admin.
If the confirmation result isn't successful, then your app should reject the payment.

To test a negative confirmation result (confirmation_result=false), do the following:
- Configure a product to track inventory
- Initiate a checkout with this product
- Proceed with a payment that triggers a 3DS challenge
- When the consumer is on the challenge, reset the inventory to 0
- Complete the challenge
The paymentSessionConfirm mutation should be called by your payments app and Shopify should then send a negative confirmation result (confirmation_result=false) to the app's confirm session URL.

Anchor to Test error scenariosTest error scenarios

If you want to test out an error scenario in the template, then set the last name in a checkout to any PaymentSessionStateRejectedReason, and then complete the checkout as normal. The app template receives this code and automatically rejects the payment with it.

PaymentSessionStateRejectedReason