Create Saved Payment Method Asynchronously

Use the asynchronous flow when payment gateways generate tokens asynchronously. You create the SPM record with a Pending status, and the token is updated later via a webhook notification.

Here’s the high-level workflow for creating a saved payment method record asynchronously.

High-level workflow diagram for creating a saved payment method record asynchronously using a third-party payment gateway

Here are the steps to create a saved payment method asynchronously using the tokenized payment details received from a third-party payment gateway:

The client builds the asynchronous gateway adapater. See Building a Asynchronous Gateway Adapter.
The client configures a webhook endpoint to receive notifications from the payment gateway. This webhook endpoint is mapped to Salesforce Notify API through an Apex adapter to receive notifications from payment gateway about payment events.
The client calls the payment gateway with the payment details entered through the buyer component.
The gateway returns a reference number that’s later used to correlate the asynchronous update.

The client-side component creates the saved payment method record using the SavedPaymentMethod sObject API. It sets all required fields, including:

status = Pending
gatewayToken = empty
asyncGatewayRefNumber (mandatory for async flows)

Sample JSON request

1{
2  "merchantAccountId": "8zbSM0000000F8jYAE",
3  "referenceOwnerId": "001SM00000FwMhEYAV",
4  "paymentGatewayId": "0b0SM0000002oLhYAI",
5  "Status": "Pending",
6  "usageType": "OFFSESSION",
7  "Name": "AmazonPay...001",
8  "GatewayReference": "cus_TEGn3J3WI5onpb",
9  "type": "extd_wallet",
10  "Checksum": "UNIQUE_GATEWAY_HASH_Wallet_10001",
11  "ExtendedPaymentMethodType": "amazon_pay",
12  "last4": "1234"
13}

Sample JSON response

1{
2  "id": "12qSM000000qfS6YAI",
3  "success": true,
4  "errors": []
5}

When the token is generated, the gateway sends a webhook to the configured endpoint with the same AsyncGatewayRefNumber. Upon receiving this notification, the SPM record status is updated to Active, and the gateway token is stored in the SavedPaymentMethod object.

Salesforce Commerce Payments Notify API for Stripe

Resource: /commerce/payments/notify/stripe

Here’s a sample Stripe notify response:

1{
2  "id": "evt_1LgJRtSGZlJjI7oJelLGgSCg",
3  "object": "event",
4  "api_version": "2020-03-02",
5  "created": 1662776977,
6  "data": {
7    "object": {
8      "id": "acct_1M6wYxIDXrazRzyT",
9      "object": "account",
10      "business_profile": {
11        "mcc": "5691",
12        "name": null,
13        "support_address": null,
14        "support_email": null,
15        "support_phone": "+917331163878",
16        "support_url": null,
17        "url": "https://www.salesforce.com"
18      },
19      "capabilities": {
20        "card_payments": "inactive",
21        "transfers": "active"
22      },
23      "charges_enabled": true,
24      "controller": {
25        "type": "application"
26      },
27      "country": "IN",
28      "default_currency": "inr",
29      "details_submitted": true,
30      "email": "harish.lnmiit@gmail.com",
31      "payouts_enabled": true,
32      "settings": {
33        "bacs_debit_payments": {},
34        "branding": {
35          "icon": null,
36          "logo": null,
37          "primary_color": null,
38          "secondary_color": null
39        },
40        "card_issuing": {
41          "tos_acceptance": {
42            "date": null,
43            "ip": null
44          }
45        },
46        "card_payments": {
47          "statement_descriptor_prefix": "KIAA",
48          "statement_descriptor_prefix_kanji": null,
49          "statement_descriptor_prefix_kana": null
50        },
51        "dashboard": {
52          "display_name": "INAccount1",
53          "timezone": "Etc/UTC"
54        },
55        "payments": {
56          "statement_descriptor": "KIAAN",
57          "statement_descriptor_kana": null,
58          "statement_descriptor_kanji": null
59        },
60        "sepa_debit_payments": {}
61      },
62      "type": "standard"
63    },
64    "previous_attributes": {}
65  },
66  "livemode": true,
67  "pending_webhooks": 1,
68  "request": {
69    "id": null,
70    "idempotency_key": null
71  },
72  "type": "account.updated"
73}

Here’s a sample Adyen async response:

1{
2  "live": "false",
3  "notificationItems": [
4    {
5      "NotificationRequestItem": {
6        "eventCode": "RECURRING_CONTRACT",
7        "success": "true",
8        "merchantReference": "KLARNA_TOKENIZE_TEST_EUR",
9        "pspReference": "Q26N98PBKQ7F42W5",
10        "paymentMethod": "klarna",
11        "merchantAccountCode": "Amazon879ECOM",
12        "originalReference": "KB44M8CFZRRPDKV5",
13        "amount": {
14          "currency": "EUR",
15          "value": 100
16        },
17        "additionalData": {
18          "recurring.shopperReference": "UNIQUE_SHOPPER_ID_12345",
19          "recurring.recurringDetailReference": "Q26N98PBKQ7F42W5"
20        }
21      }
22    }
23  ]
24}

Here’s a sample user interface that shows the status of a Saved Payment Method record before and after the webhook endpoint notification is sent.

Before webhook:

Saved Payment Method record showing Pending status before the webhook notification is received from the payment gateway

After webhook:

Saved Payment Method record showing Active status and stored gateway token after the webhook notification is received

See Also