Gift Cards

---

PaysafeCard has expanded its portfolio of cash-based payment methods in the United States, adding the acceptance of popular retail gift cards such as CVS/pharmacy and Dollar General, as well as Obucks cards.

This documentation explains how to start accepting gift card payment options as an add-on to the classic PaysafeCard integration

Where to start

To accept gift card payments on your U.S. checkout:

1. In case you are an existing PaysafeCard merchant, please contact your account manager for further guidance on the activation process and contractual steps. If you are not yet transacting with us, become a partner here.
2. Upon completion of the above, PaysafeCard will activate the gift cards on your USD MID (Merchant ID) and, if applicable, RC (Reporting Criteria).
3. You will need to complete two technical integration changes as listed below.

Gift card payment flow

1. The customer selects a gift card button at the merchant checkout (i.e. CVS, Dollar General or oBucks)
2. The merchant initiates the payment by passing the amount, currency, payment instrument and other necessary parameters
3. PaysafeCard redirects the customer to the payment panel, where the customer completes the payment by entering the gift card number and PIN
4. Once the payment is completed, PaysafeCard sends a payment notification to the merchant via the notification URL
5. PaysafeCard redirects the customer back to the merchant via the success URL
6. The merchant captures the payment and delivers the goods to the customer

Payment panel gift card redemption

Technical changes

Technical changes needed (for U.S. checkouts only):

1. Required: The button must be changed on the merchant checkout by configuring the button endpoints which dynamically changes the button based on the MID, RC, country, instrument type and subtype.
2. Required: The payment must be created based on the option chosen by the customer at the checkout and achieved by passing the correct instrument type and subtype when initiating the payment.
3. Optional: Integrate the payment notification payload in JSON which enables the merchant to distinguish which payment instrument was used for the transaction.

Configuring the button endpoints

PaysafeCard provides .svg buttons via the following endpoints described in the section below:

Environment	Url
Test	https://customer.test.at.paysafecard.com/rest/payment/logo.svg?`mid`=MID&`submerchant_id`=SUBMERCHANT_ID&`country`=COUNTRY&`payment_instrument`=PAYMENT_INSTRUMENT&`payment_instrument_subtype`=PAYMENT_INSTRUMENT_SUBTYPE
Production	https://customer.cc.at.paysafecard.com/rest/payment/logo.svg?`mid`=MID&`submerchant_id`=SUBMERCHANT_ID&`country`=COUNTRY&`payment_instrument`=PAYMENT_INSTRUMENT&`payment_instrument_subtype`=PAYMENT_INSTRUMENT_SUBTYPE

To get the correct button by type of integration and country, the following parameters must be specified:

Parameter	Description	Format
mid (mandatory)	The Merchant ID is the unique merchant identifier and also defines the currency being used for a transaction.	default value of 10 digits
submerchant_id (mandatory - only if any is set for the MID)	The Reporting Criteria (or submerchant id) is used to classify sub-merchants. The setup of a reporting criteria must be agreed with PaysafeCard.	max. value of 8 alphanumeric characters
country (mandatory)	The target country.	2-digit ISO 3166-1
payment_instrument (optional)	The payment instrument gives the possibility to split the logo shown between PaysafeCard or the gift card options.	"paysafecard" or "giftcard"
payment_instrument_subtype (optional)	If a gift card was used for the payment instrument, the logo for each gift card option can be shown separately by defining a subtype.	"cvspharmacy" or "dollargeneral" or "openbuckscard"

Below is a list of payment buttons and text options to use:

Button / Text Requirements	Button configuration options
CVS gift card	https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard&payment_instrument_subtype=cvspharmacy
Dollar General gift card	https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard&payment_instrument_subtype=dollargeneral
Obucks gift card	https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard&payment_instrument_subtype=openbuckscard
paysafecard	https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=paysafecard
gift cards	https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US&payment_instrument=giftcard
Cash and gift cards	https://customer.test.at.paysafecard.com/rest/payment/logo.svg?mid=1100000000&country=US

IMPORTANT:

For production, change the following in the button endpoints:

https://customer.test.at.paysafecard.com

to

https://customer.cc.at.paysafecard.com

Brand guidelines

When implementing the button, graphics or text, please follow each brand guideline or as indicated in the button configurations.

Examples of merchant checkout button and text variations:

IMPORTANT: For alternative button layouts, dimensions, file formats or text please contact your PaysafeCard account manager.

Payment Process

1. The customer selects the payment method at the merchant's checkout: PaysafeCard or one of the gift card options (CVS, Dollar General or oBucks)

2. The merchant creates a disposition: the merchant makes the SOAP request createDisposition using the correct INSTRUMENT and INSTRUMENT_SUBTYPE

   • If the result and error code is 0, the merchant redirects the customer to the payment panel

   • If the result or error code is not 0, the merchants shows an error message to the customer:

     "Transaction could not be initiated due to connection problems. If the problem persists, please contact our (merchant) support."

3. Redirection to the payment panel with getCustomerPanel: The customer reaches the payment panel and enters a valid PaysafeCard PIN, or gift card number and PIN and clicks “Pay”

   • Verification on PaysafeCard or Openbucks side if the data entered is valid
   • If the customer cancels the transaction on the payment panel, please show the following error message: "Transaction cancelled by user"

4. Payment notification delivery: Since the card is assigned to the transaction (transaction status "S"), PaysafeCard sends a notification to the pn_url

5. pnUrl handling: Right after the payment notification delivery, the merchant performs the request getSerialNumbers to check the status of the transaction

   • If getSerialNumbersreturns the status "S", immediately perform the executeDebit request
     • If the response to executeDebit is result and error code is 0, the merchant makes a user account top up accordingly or deliver the goods

6. Redirection to the okUrl: PaysafeCard redirects the customer to the okUrl

7. okUrl handling: The merchant checks with getSerialNumbers, the status of the transaction

   • If getSerialNumbers returns "O", the merchant shows a success message to the customer

   • If the status is "S", the merchant performs executeDebit

     • If the result and error code is 0, the merchant makes a user account top up accordingly or delivers the goods and shows a success message to the customer
     • If the result or error code is not 0, the merchant shows an error message to the customer

   • If the response to getSerialNumbers result or error code is not 0 , the merchant shows an error message to the customer:

     • "The transaction could not be completed. This may have happened due to a temporary connection problem. Please press the "reload" button in your browser to retry completing your transaction. If the problem persists, please contact our (merchant)support.

Initiating a gift card payment

Restrictions

The disposition restrictions (INSTRUMENT and INSTRUMENT_SUBTYPE) give the possibility to create a disposition for the specific option chosen by the customer at the merchant's checkout.

Parameter	Type	Description	Possible values
dispositionRestrictions	Array	The payment restrictions array.
key	String	Value to specify what type of restriction should be applied for the transaction.	"INSTRUMENT" or "INSTRUMENT_SUBTYPE"
value	String	Value to define the available options for a certain restriction.	INSTRUMENT:"paysafecard", "giftcard" INSTRUMENT_SUBTYPE: "cvspharmacy","openbuckscard", "dollargeneral"

createDisposition example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:pscservice">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:createDisposition>
         <urn:username>username_SOAP</urn:username>
         <urn:password>password_SOAP</urn:password>
         <urn:mtid>mtid_soap</urn:mtid>
         <urn:subId>reporting_criteria</urn:subId>

         <urn:amount>10.00</urn:amount>
         <urn:currency>USD</urn:currency>

         <urn:okUrl>https://www.paysafecard.com/okURL</urn:okUrl>
         <urn:nokUrl>https://www.paysafecard.com/nokURL</urn:nokUrl>
         <urn:merchantclientid>customer1</urn:merchantclientid>
         <urn:pnUrl>https://www.paysafecard.com/pnURL</urn:pnUrl>

        <urn:dispositionRestrictions>
        <urn:key>INSTRUMENT</urn:key>
        <urn:value>giftcard</urn:value>
        </urn:dispositionRestrictions>

        <urn:dispositionRestrictions>
        <urn:key>INSTRUMENT_SUBTYPE</urn:key>
        <urn:value>openbuckscard</urn:value>
        </urn:dispositionRestrictions>

         <urn:customerDetail>CUSTOMER_ID</urn:customerDetail>

      </urn:createDisposition>
   </soapenv:Body>
</soapenv:Envelope>

New Error Code

Error code "2039" indicates that the one of the values passed in INSTRUMENT or INSTRUMENT_SUBTYPE, is not a valid value.

<ns1:createDispositionResponse>
    <ns1:createDispositionReturn>
        <ns1:mtid>1607092862</ns1:mtid>
        <ns1:resultCode>1</ns1:resultCode>
        <ns1:errorCode>2039</ns1:errorCode>
    </ns1:createDispositionReturn>
</ns1:createDispositionResponse>

Gift card payment Limits

The current minimum amount for gift card payments is: 0.10 USD

The current maximum amount for gift card payments is: 1000.00 USD

If a gift card payment is created for an amount smaller than 0.10 USD, the customer will see an error message in the payment panel.