Overview

Before Skipify can submit a payment on your behalf in either Expedited Guest Checkout or the Skipify Button, we need to know important information about the overall order. Because this information differs between businesses, we require that you implement callbacks so that we can obtain and utilize this information properly.

Order Callbacks Overview

There are five callbacks available via the SDK: orderDetailsCallback, success, error, getOrderId, and onClose. The subsections below contain descriptions about the callbacks and the following sections include details about the parameters in these callbacks.

Order Callback Descriptions

Callback	Required?	Time of Callback	Description
orderDetailsCallback	Yes	Start of checkout	This callback has a function inside of it called createOrder, which is how you craft an Order using Skipify. We will take this information and submit it for payment with your preferred gateway.
success	Yes	After payment is submitted	This callback triggers when Skipify successfully processes an order with your gateway. The payload of this callback will provide you key information about the order, including the gateway response.
error	Yes	After payment is submitted	This callback triggers when Skipify encounters an error during payment submission to your gateway. The payload of this callback will provide you key information about the error, including the ID, error code, and error message.
getOrderId	No	After the order is created	This callback is optional and triggers when Skipify successfully creates an order. The payload of this callback will provide you with the Skipify ID for the order.
onClose	No	After the user closes the Skipify modal	This callback is optional and triggers when a user closes the Skipify modal. There is no payload for this call.

Order Callback Example

The three required callbacks (orderDetailsCallback, success, error) and optional callbacks need to be implemented together in order to work successfully. The example below shows how to properly set up the various callbacks to occur at the right time during the process.

<body>  
    <script> 
        new GoCartSDK.Button({          
            orderDetailsCallback: async (actions) => {
                actions.createOrder({
                    lineItems: [ // Required
                        {
                          name: 'some item', 
                          amount: 100, 
                          SKU: 'SKU', 
                          category: 'some category' 
                        },
                    ], 
                    subtotal: 100, 
                    total: 100, 
                    orderId: 'your_order_id', 
                    orderDescription: 'some_description', 
                    currencyCode: 'USD' 
                });
            },
            success: (orderId, customerInfo, shippingInfo, billingInfo, shippingMethod, taxes, transactionDetails) => { 
                console.log(`Successfully processed order ${orderId}`); 
            }, 
            error: (orderId, errorCode, errorMessage) => { 
                console.log(`Error processing order ${orderId}.`); 
            },
            theme: 'light', // Optional; see the 'SDK: The GoCart Button' page for details
            getOrderId: (orderId) => { console.log(orderId); }, // Optional; see details below
            onClose: () => { console.log('GoCart was closed!'); }, // Optional; see details below
       }).render(“my-button-container”) // Details for this can be found in the "SDK: The GoCart Button" page;
    </script>
</body>

📘
Note: It is possible to perform asynchronous calls during these callbacks
Ex: If you need to generate a new ID associated with your order, you can await those calls in your callbacks.

📘
Note: Additional required fields

The lineItems collection is required when creating an order (collection can be empty)

For each line item, SKU (all caps) is a required field

Order Details Callback

The orderDetailsCallback is used to submit orders to Skipify. See the page Creating an Order for details about how to setup and use this callback.

Success Callback

The success callback triggers when Skipify successfully processes an order with your gateway. The payload of this callback includes information about the order, including associated addresses, tax/shipping fees, and the payment gateway response.

📘
A note on parameter order
The order of parameters in the success callback is: orderId, customerInfo, shippingInfo, billingInfo, shippingMethod, taxes, transactionDetails. When you create your callback, it must accept the parameters in this order, even if you do not intend to use them.
For example, you must do:
success: (orderId, customerInfo, shippingInfo, billingInfo, shippingMethod, taxes, transactionDetails) => {
/// your code here
}
If you omit parameters that you will not use, they will still be passed to your success callback in the default order.
For example, if you try to do:
success: (orderId, billingInfo, taxes) => {
/// your code here
}
The customerInfo will actually be passed into the billingInfo parameter space, so you will not be accessing the billingInfo, but the customerInfo.

Order ID

The unique orderId generated for the order by Skipify when attempting to submit an order for payment.

📘
A note on orderID's
The orderId generated by Skipify is distinct from the orderId you submit with the createOrder callback. Use Skipify's orderId for making calls to our API endpoints. When making a call to the GET order endpoint, the orderId you originally submitted with the createOrder callback will be returned as the merchantOrderId in the response body.

Customer Info

The customerInfo of the success callback refers to the saved customer information used for creating the Skipify order.

Customer Info Parameters

Parameter	Type	Description
email	string	The email address associated with the user.
paymentMethod	object	The object containing details of the payment method used by the customer for the order.
phoneNumber	string	The phone number associated with the customer's account.

Customer Info example

{
 email: "[email protected]",
 paymentMethod: {
  address: {
   address1: "1 16th St",
   address2: null,
   city: "Denver",
   company: null,
   country: "US",
   externalId: "b9b778e8-2129-4458-8ccc-fe968301e0ff",
   firstName: "FirstName",
   lastName: "LastName",
   isDefaultBilling: true,
   isDefaultShipping: true,
   phoneNumber: "11111111111", // Note: this is optional and therefore will sometimes be null
   state: "CO",
   zip: "80202"
  },
  addressId: 5168,
  cardBrand: "Mastercard",
  expMonth: 12,
  expYear: 2026,
  externalId: "25af831b-b6da-4fb2-8b0d-9a5d458d4b43",
  fullNameCard: "FirstName LastName",
  isDefault: true,
  last4CardNumber: "4444",
  needsCvv: false,
  nickName: null,
  paymentToken: "5555553147074444",
  storedCredentialsIdentifier: null
 },
 phoneNumber: "11111111111"
}

Billing Info

The billingInfo of the success callback refers to the saved billing information used for creating the Skipify order.

Billing Info Parameters

Parameter	Type	Description
firstName	String	The first name of this billing address
lastName	String	The last name of this billing address
company	String	The company of the billing address, if applicable. This field is optional and may sometimes be `null`
address1	String	The first line of this billing address, usually corresponding to the street address
address2	String	Additional line of this billing address, corresponding to unit or apartment numbers, etc. if applicable. This field is optional and may be `null`.
city	String	The city of the billing address
state	String	The abbreviation of the state of the billing address
zip	String	The zip code of the billing address
country	String	The country of the billing address
phoneNumber	String	The phone number associated with this address. This field is optional and may sometimes be `null`
isDefaultBilling	Boolean	Notes if this address is the customer's default billing address
isDefaultShipping	Boolean	Notes if this address is the customer's default shipping address
externalId	String	The unique identifier for this address assigned by Skipify

Billing Info Example

{
    "firstName": "John",
    "lastName": "Doe",
    "address1": "1 New Street",
    "address2": "Apt. 2", // Note: this is optional and therefore will sometimes be null
    "company": "GoCart Pay", // Note: this is optional and therefore will sometimes be null
    "city": "Denver",
    "state": "CO",
    "zip": "80220",
    "country": "United States",
    "phoneNumber": "3035551234", // Note: this is optional and therefore will sometimes be null
    "isDefaultBilling": true,
    "isDefaultShipping": false,
    "externalId": "string"
}

Shipping Info

The shippingInfo of the success callback refers to the saved billing information used for the Skipify order. The success callback will return an empty object for orders that do not include shipping.

Shipping Info Parameters

Parameter	Type	Description
firstName	String	The first name of this billing address
lastName	String	The last name of this billing address
company	String	The company of the billing address, if applicable
address1	String	The first line of this billing address, usually corresponding to the street address
address2	String	Additional line of this billing address, corresponding to unit or apartment numbers, etc. if applicable
city	String	The city of the billing address
state	String	The abbreviation of the state of the billing address
zip	String	The zip code of the billing address
country	String	The country of the billing address
phoneNumber	String	The phone number associated with this address
isDefaultBilling	Boolean	Notes if this address is the customer's default billing address
isDefaultShipping	Boolean	Notes if this address is the customer's default shipping address
externalId	String	The unique identifier for this address assigned by Skipify

Shipping Info Example

{
    "firstName": "John",
    "lastName": "Doe",
    "address1": "1 New Street",
    "address2": "Apt. 2",
    "company": "GoCart Pay",
    "city": "Denver",
    "state": "CO",
    "zip": "80220",
    "country": "United States",
    "phoneNumber": "3035551234",
    "isDefaultBilling": false,
    "isDefaultShipping": true,
    "externalId": "external-shipping-id-123"
}

Shipping Method

The shippingMethod of the success callback includes details about the shipping method and pricing returned from the shipping query.

Shipping Method Parameters

Parameter	Type	Description
externalId	String	The unique identifier for the selected shipping method assigned by Skipify
name	String	The name of the selected shipping method for this order
price	Integer	The cost of the selected shipping method for this order

Shipping Method Example

{
    "externalId":"external-shipping-method-id-123",
    "name": "GoCart Express",
    "price": 0
}

Taxes

The taxes associated with the the order, in cents (ex: 500 corresponds to $5)

Transaction Details

For successful payments, the success callback will pass through transactionDetails (see success callback above), which contains the parameters listed below. These parameters are a passthrough of the gateway's response. You can use these responses to interact with the gateway as if you had submitted the transaction yourself.

Transaction Details Parameters

Parameter	Description
networkTransactionId	The transaction identifier the payment gateway receives from the card network (VISA, MC, Amex, etc.). It can be null if the card network doesn't send anything back. As a best practice, Merchants should send this as the stored credential identifier on subsequent operations (Captures/Refunds) on the authorization/sale since we are storing the card and the payment was made using stored credential.
gatewayTransactionId	The TransactionId that the merchant can use to perform subsequent operations (Void/Captures/Refunds/Reversals) on the initial authorization/sale made by Skipify. In some cases the gateway generates this themselves on their end. But some gateways like Raft and WPG require we generate it on our side then send it to them (GC00000000013-00 n this example. GC = Skipify)
gatewayResponse	Response we receive from the payment gateway. We return this so that merchants are able to parse it and grab anything they might need. This one is for RAFT. Note that networkTransactionId is the same as the APITransactionID and the gatewayTransactionId is the same as the VisaTransactionId. We strip them out since they are the only things merchants need to perform the subsequent operations on the initial auth/sale. This is usually either a XML or JSON string, depending on what markup language the payment gateway utilizes. Express is old school and uses XML.

Transaction Details Example

{
  "networkTransactionId": "220610170424296",
  "gatewayTransactionId": "GC00000000013-00",
  "gatewayResponse": {
    "creditauthresponse": { 
      "ReturnCode": "0000",
      "ReasonCode": "0000",
      "CardInfo": {
        "CardProductCode": "A C" 
      },
      "AddressVerificationData": {
        "AVSResult": "Y" 
      },
      "VisaSpecificData": { 
        "VisaSpendQualifier": "Q", 
        "VisaResponseCode": "00",
        "VisaValidationCode": "HNZX",
        "VisaCardLevelResults": "A",
        "VisaTransactionId": "220610170424296",
        "VisaAuthCharId": "N" 
      },
      "ReferenceTraceNumbers": { 
        "RetrievalREFNumber": "206117042563", 
        "NetworkRefNumber": "206117042563", 
        "SystemTraceNumber": "003068",
        "AuthorizationNumber": "597261"
      },
      "CustomerInformation": {
        "IssuerCountryCode": "752"
      },
      "SettlementData": {
        "SettlementDate": "20220302",
        "SettlementNetwork": "OMPS",
        "RegulationIndicator": "0"
      },
      "WorldPayRoutingData": {
        "NetworkId": "BASE" 
      },
      "APITransactionID": "GC00000000013-00",
      "ResponseCode": "000",
      "AuthorizationSource":"5"
    }
  }
}

Error Callback

The error callback triggers when Skipify encounters an error during payment submission to your gateway. The payload of this callback will provide you key information about the error, including the error code and error message.

Order Id

The unique orderId generated for the order by Skipify when attempting to submit an order for payment.

Error Code & Error Message

For unsuccessful payments, the error callback will passthrough errorCode and errorMessage parameters.

errorCode	errorMessage	Description
990	Card was declined	The card processor was unable to process the card, usually due to bad credentials
995	Unable to process card	The card processor was able to process the card, but card was declined

📘
Skipify has credit cards test data available
Remember to use Implementation Test Data to setup handling these errors while implementing in Skipify's Staging environment.

Get Order ID

The optional getOrder callback triggers as soon as an order is created. Skipify creates an order before launching the modal. This callback returns the orderId of the order so that it can be referenced when the user does not complete checkout (and thus bypass both the success and error callbacks).

On Close

The optional onClose callback triggers if the Skipify wallet is closed instead of completing checkout. This allows you to add custom actions when customers exit the checkout experience early (thus bypassing both the success and error callbacks).

Callbacks

Overview

Order Callbacks Overview

📘
Note: It is possible to perform asynchronous calls during these callbacks

📘
Note: Additional required fields

Order Details Callback

Success Callback

📘
A note on parameter order

📘
A note on orderID's

Customer Info Parameters

Customer Info example

Billing Info Parameters

Billing Info Example

Shipping Info Parameters

Shipping Info Example

Shipping Method Parameters

Shipping Method Example

Transaction Details Parameters

Transaction Details Example

Error Callback

📘
Skipify has credit cards test data available

Get Order ID

On Close

Overview

Order Callbacks Overview

📘Note: It is possible to perform asynchronous calls during these callbacks

📘Note: Additional required fields

Order Details Callback

Success Callback

📘A note on parameter order

📘A note on orderID's

Customer Info Parameters

Customer Info example

Billing Info Parameters

Billing Info Example

Shipping Info Parameters

Shipping Info Example

Shipping Method Parameters

Shipping Method Example

Transaction Details Parameters

Transaction Details Example

Error Callback

📘Skipify has credit cards test data available

Get Order ID

On Close

📘
Note: It is possible to perform asynchronous calls during these callbacks

📘
Note: Additional required fields

📘
A note on parameter order

📘
A note on orderID's

📘
Skipify has credit cards test data available