Guides
Back to skipify.comContact Us

Callbacks

Learn more about the callbacks required for Connected Checkout and the Skipify Button

Suggest Edits

Overview

Before Skipify can submit a payment on your behalf in either Connected Checkout or the Skipify Button, we need to gather some information about the order. Because this info may differ between businesses, we require that you implement callbacks in order for us to obtain and utilize the information properly.

Order Callbacks Overview

There are five callbacks available via the SDK:

  • orderDetailsCallback
  • success
  • error
  • getOrderId
  • onClose

Order Callback Descriptions

ActionRequired?TimeDescription
orderDetailsCallbackYesStart of checkoutThis 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.
successYesAfter payment is submittedThis 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.
errorYesAfter payment is submittedThis 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.
getOrderIdNoAfter the order is createdThis 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.
onCloseNoAfter the user closes the Skipify modalThis 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 window.GoCartSDK.Button({         
          orderDetailsCallback: async (actions) => {
                actions.createOrder({
                    lineItems: [
                        {
                          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}.`); 
            },
            getOrderId: (orderId) => { console.log(orderId); }, // Optional
            onClose: () => { console.log('GoCart was closed!'); }, // Optional
        })).guestRedirect(email); // Details for this can be found in the "SDK: Expedited Guest Checkout" page
    </script>
</body>

📘

Note

It is possible to perform asynchronous calls during these callbacks!

Example: If you need to generate a new ID associated with your order, you can await those calls in your callbacks.

🚧

Important!

Here are some 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 Creating an Order section for details on 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.

📘

Note

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

A unique orderId will be generated for each order by Skipify when attempting to submit an order for payment.

🚧

Important!

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

ParameterTypeDescription
emailstringThe email address associated with the user.
paymentMethodobjectThe object containing details of the payment method used by the customer for the order.
phoneNumberstringThe 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

ParameterTypeDescription
firstNameStringThe first name of this billing address
lastNameStringThe last name of this billing address
companyStringThe company of the billing address, if applicable. This field is optional and may sometimes be null
address1StringThe first line of this billing address, usually corresponding to the street address
address2StringAdditional line of this billing address, corresponding to unit or apartment numbers, etc. if applicable. This field is optional and may sometimes be null
cityStringThe city of the billing address
stateStringThe abbreviation of the state of the billing address
ZipStringThe zip code of the billing address
countryStringThe country of the billing address
phoneNumberStringThe phone number associated with this address. This field is optional and may sometimes be null
isDefaultBillingBooleanNotes if this address is the customer's default billing address
isDefaultShippingBooleanNotes if this address is the customer's default shipping address
externalIdStringThe 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

ParameterTypeDescription
firstNameStringThe first name of this billing address
lastNameStringThe last name of this billing address
companyStringThe company of the billing address, if applicable
address1StringThe first line of this billing address, usually corresponding to the street address
address2StringAdditional line of this billing address, corresponding to unit or apartment numbers, etc. if applicable
cityStringThe city of the billing address
stateStringThe abbreviation of the state of the billing address
zipStringThe zip code of the billing address
countryStringThe country of the billing address
phoneNumberStringThe phone number associated with this address
isDefaultBillingBooleanNotes if this address is the customer's default billing address
isDefaultShippingBooleanNotes if this address is the customer's default shipping address
externalIdStringThe 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

ParameterTypeDescription
externalIdStringThe unique identifier for the selected shipping method assigned by Skipify
nameStringThe name of the selected shipping method for this order
priceIntegerThe 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 (Example: 500 corresponds to $5)

Transaction Details

For successful payments, the success callback will pass through transactionDetails, 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

ParameterDescription
networkTransactionIdThe 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.
gatewayTransactionIdThe 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)
gatewayResponseResponse 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.
stpReferenceNumAn assigned reference number on each transaction that is returned to us from the RAFT gateway. It should be sent by the terminal on follow-up messages in order to match back to the original transaction.

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.

Error Code & Error Message

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

errorCodeerrorMessageDescription
990Card was declinedThe card processor was unable to process the card, usually due to bad credentials
995Unable to process cardThe card processor was able to process the card, but card was declined
-1nullGeneric error code; contact your implementation manager for help troubleshooting

👍

Test data is available!

Remember to use our Implementation Test Data to setup handling of these errors while you're 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 (this will 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 (this will bypass both the success and error callbacks).


Skipify baner with link to contact us form

Updated about 1 year ago