This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Using card number origin values

The PUT request message body for authorizing a payment includes a cardNumberOrigin value. This value indicates whether:

  • The guest provided the credit card information directly (END_USER)

  • The credit card information was retrieved from secure storage (PARTNER_VAULT)

To ensure that your guests' transactions receive adequate fraud protection, your integration must send the cardNumberOrigin value that correctly indicates the way that your integration acquired credit card information.

  • If a guest provided credit card information directly, you must set the cardNumberOrigin value to END_USER.

  • If your integration retrieved the credit card information from secure storage, you must set the cardNumberOrigin value to PARTNER_VAULT.

Important

If you do not include the cardNumberOrigin value that correctly indicates the source of the credit card information, you reduce the effectiveness of the fraud detection provided by the Toast platform. Make sure that your integration includes the correct cardNumberOrigin value to ensure the most accurate fraud detection and to minimize unnecessarily declined transactions.

Note

When the cardNumberOrigin value is END_USER (the guest provided credit card information directly), the PaymentRequestMetadata object in the requestMetadata value must include the following values:

  • cardFirst6

  • cardLast4

  • billingAddress

  • guestIdentifier

The following table provides more information about the values you include in the cardNumberOrigin value in a PaymentAuthorization object in the message body parameter of a credit card authorization request.

cardNumberOrigin values

Value

Explanation

END_USER

The guest provided the credit card information directly.

When the cardNumberOrigin value is END_USER, the PaymentRequestMetadata object in the requestMetadata value must include:

  • cardFirst6

  • cardLast4

  • billingAddress

  • guestIdentifier

PARTNER_VAULT

Your integration retrieved the credit card information from secure storage.

Even when the cardNumberOrigin value is PARTNER_VAULT, including more information about a credit card in the values in the PaymentRequestMetadata object in the requestMetadata value provides additional fraud protection for your credit card authorization.


Note

When you authorize a payment for a new credit card, you must set the cardNumberOrigin value to END_USER, even if you use an external credit card vaulting service to save guests' credit cards. Setting the cardNumberOrigin value to END_USER gives you additional fraud protection when authorizing payment for new credit cards.