Create a Saved Payment Method Using the sObject API

Use SavedPaymentMethod sObject API to create Saved Payment Method (SPM) records directly in Salesforce. To import payment details previously tokenized and stored by your payment gateway, include the existing payment token and related tokenized details in your request. The API creates the SavedPaymentMethod record and returns the Salesforce-generated SPM ID, which you then use for future transactions initiated from Salesforce.

Resource

/services/data/<version>/sobjects/SavedPaymentMethod

Resource example

https://<my-domain>.salesforce.com/services/data/66.0/sobjects/SavedPaymentMethod

HTTP method

POST

Request body

The API validates the input and creates the record in the SavedPaymentMethod object.

Sample JSON request

{
  "merchantAccountId": "8zbSM0000000CxFYAU",
  "referenceOwnerId": "001SM00000GPtUqYAL",
  "paymentGatewayId": "0b0SM0000002VJ3YAM",
  "gatewayReference": "cus_Ssp02fOccymkwz",
  "status": "Active",
  "type": "card",
  "usageType": "OffSession",
  "name": "Visa....1111",
  "checksum": "unique_hash_ahht",
  "gatewayToken": "pm_1Rx3MvRBJ3juuXWQYIxYgVMc",
  "last4": "1234",
  "processingMode": "External",
  "expiryYear": "2030",
  "expiryMonth": "09"
}

Name	Type	Description	Required or Optional
`checksum`	String	Specifies the unique value provided by the payment gateway. For example, use `pspReference` for Adyen and `fingerprint` for Stripe. The Checksum field is used in conjunction with paymentgatewayId and referenceOwnerId to enforce uniqueness and prevent duplicate SPM creation. An index on these three fields supports efficient duplicate detection.	Required
`expiryYear`	String	The year the payment method expires.	Optional <ul><li>This field is required for the card payment method. </li></ul>
`expiryMonth`	String	The month the payment method expires.	Optional <ul><li>This field is required for the card payment method. </li></ul>
`extendedPaymentMethodType`	String	The actual payment method type for extended APM/Wallet scenarios.	Optional <ul><li>This field is required if the `type` is `extd_wallet` or `extd_apm_type`.</li></ul>
`gatewayToken`	String	An unencrypted unique token ID generated by the payment gateway to represent the card payment method during transactions.	Optional <ul><li> This field is required for creating an active Saved Payment Method. </li></ul>
`gatewayReference`	String	A reference to the saved payment owner at the payment gateway. For example, a Stripe customer ID.	Required
`merchantAccountId`	String	The Salesforce Payments merchant account ID.	Required
`name`	String	The name of the saved payment method.	Required
`paymentGatewayId`	String	The payment gateway that is used to create a gateway token. For transactions with a saved payment method in Salesforce, this field stores the payment gateway ID used in the transaction. This field is a relationship field.	Required
`processingMode`	String	Specifies the origin of the saved payment method. Possible values are: <ul><li>`External`–Set when importing an existing token using the SPM sObject API.</li><li>`Salesforce`–Set when creating an SPM record using Commerce CCS APIs.</li></ul>	Optional <ul><li>Specify this field value as External when making the SPM sObject API call.</li></ul>
`referenceOwnerId`	String	The ID of the Account or Contact record that owns the payment method.	Required
`status`	String	The status of the saved payment method. Possible values are: <ul><li>`Active`</li><li>`AwaitingPayment`</li><li>`Errored—Failed`</li><li>`Expired`</li></ul>	Required
`type`	String	The type of saved payment method. Possible values are: <ul><li>`au_becs_debit`</li><li>`bacs_debit`</li><li>`bancontact`</li><li>`card`</li><li>`ideal`</li><li>`sepa_debit`</li><li>`us_bank_account`–ACH Direct Debit</li></ul>	Required
`usageType`	String	Determines whether the payment method is used on or off session. Possible values are: <ul><li>`OffSession`</li><li>`OnSession`</li><li>`RestrictedOffSession`</li></ul>	Required

Response body

The API returns the newly generated Salesforce Saved Payment Method ID of the imported record.

Sample JSON response

{
  "id": "12qSM000000qKsHYAU",
  "success": true,
  "errors": []
}

Name	Type	Description
`id`	String	The ID of the saved payment method record.
`success`	String	Indicates whether the saved payment method record was created successfully.
`errors`	String	Specifies the errors that occurred during the saved payment method creation request.

You can use the Saved Payment Method creation process to bulk-import saved payment method records. For more information on bulk import, see Bulk API.

See Also