Sample API Helper Contracts

You can reference these sample helper contracts with transaction API contracts. All contracts are specified with "$ref", such as "$ref" : "#/definitions/PaymentTransactionRequest".

Address Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "Address" : {
      "type" : "object",
      "typeName" : "Address",
      "description": "Address object. Supports custom properties.",
      "x-extends": ["com.demandware.core.transport.data.CustomProperties"],
      "properties" : {
        "address1" : {
          "type" : "string",
          "required" : false,
          "description" : "Address first line."
        },
        "address2" : {
          "type" : "string",
          "required" : false,
          "description" : "Address second line."
        },
        "city" : {
          "type" : "string",
          "required" : false,
          "description" : "Address city."
        },
        "postal_code" : {
          "type" : "string",
          "required" : false,
          "description" : "Zip or postal code."
        },
        "state_code" : {
          "type" : "string",
          "required" : false,
          "description" : "State code."
        },
        "country_code" : {
          "type" : "string",
          "required" : false,
          "description" : "Country code, Iso Alpha-2 codes such as US,GB,FR."
        }
      }
    }
  }
}

BankAccount Contract

 {
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "BankAccount" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentInstrument"
      }, {
        "type" : "object",
        "typeName" : "BankAccount",
        "description" : "Details of bank account.",
        "properties" : {
          "account_number" : {
            "type" : "string",
            "required" : false,
            "description" : "Unmasked account number or token representing the account number. See property 'number_format'."
          },
          "account_number_format" : {
            "type" : "string",
            "required" : true,
            "description" : "Whether the 'number' property is plain text or is a token previously created by the payment provider",
            "enum" : [ "plain_text", "tokenized" ]
          },
          "bank_identifier_code" : {
            "type" : "string",
            "required" : false,
            "description" : "Bank identifier code"
          },
          "bank_name" : {
            "type" : "string",
            "required" : false,
            "description" : "Name of the bank."
          },
          "account_type" : {
            "type" : "string",
            "required" : false,
            "description" : "Optional type of account"
          }
        }
      } ]
    }
  }
}

BillingInformation Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "BillingInformation" : {
      "type" : "object",
      "typeName" : "BillingInformation",
      "description": "Billing information including the billing address and contact information. Supports custom properties.",
      "x-extends": ["com.demandware.core.transport.data.CustomProperties"],
      "properties" : {
        "first_name" : {
          "type" : "string",
          "required" : false,
          "description" : "First name of person being billed."
        },
        "last_name" : {
          "type" : "string",
          "required" : false,
          "description" : "Last name of person being billed."
        },
        "national_identification_number" : {
          "type" : "string",
          "required" : false,
          "description" : "National identification number of person being billed."
        },
        "date_of_birth" : {
          "type" : "string",
          "format" : "datetime",
          "required" : false,
          "description" : "The date of birth of person being billed, (ISO-8601 format yyyy-MM-dd'T'HH:mm:ssZ e.g. 2010-01-01T12:00:00+01:00)."
        },
        "address" : {
          "type" : "object",
          "required" : false,
          "description" : "Billing address",
          "$ref" : "#/definitions/Address"
        },
        "contact" : {
          "type" : "object",
          "required" : false,
          "description" : "Contact information for person being billed",
          "$ref" : "#/definitions/ContactInfo"
        }
      }
    }
  }
}

Check Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "Check" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentInstrument"
      }, {
        "type" : "object",
        "typeName" : "Check",
        "description" : "Details of check.",
        "properties" : {
          "check_number" : {
            "type" : "string",
            "required" : false,
            "description" : "Check number."
          },
          "account_number" : {
            "type" : "string",
            "required" : false,
            "description" : "Unmasked account number or token representing the account number. See property 'number_format'."
          },
          "account_number_format" : {
            "type" : "string",
            "required" : true,
            "description" : "Whether the 'number' property is plain text or is a token previously created by the payment provider",
            "enum" : [ "plain_text", "tokenized" ]
          },
          "routing_number" : {
            "type" : "string",
            "required" : false,
            "description" : "Bank identifier code"
          },
          "bank_name" : {
            "type" : "string",
            "required" : false,
            "description" : "Name of the bank."
          },
          "account_type" : {
            "type" : "string",
            "required" : false,
            "description" : "Optional type of account"
          }
        }
      } ]
    }
  }
}

ContactInfo Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "ContactInfo" : {
      "type" : "object",
      "typeName" : "ContactInfo",
      "properties" : {
        "email" : {
          "type" : "string",
          "required" : false,
          "description" : "Email address."
        },
        "phone" : {
          "type" : "string",
          "required" : false,
          "description" : "Optional phone number."
        },
        "phone2" : {
          "type" : "string",
          "required" : false,
          "description" : "Optional phone number."
        }
      }
    }
  }
}

CreditCard Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "CreditCard" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentInstrument"
      }, {
        "type" : "object",
        "typeName" : "CreditCard",
        "description" : "Details of creditcard.",
        "properties" : {
          "card_number" : {
            "type" : "string",
            "required" : false,
            "description" : "Unmasked number or token representing the number. See property 'number_format'."
          },
          "card_number_format" : {
            "type" : "string",
            "required" : true,
            "description" : "Whether the 'number' property is plain text or is a token previously created by the payment provider",
            "enum" : [ "plain_text", "tokenized" ]
          },
          "expiration_month" : {
            "type" : "integer",
            "format" : "int32",
            "required" : false,
            "description" : "Card expires thru' month as an integer: January is 1, December is 12"
          },
          "expiration_year" : {
            "type" : "integer",
            "format" : "int32",
            "required" : false,
            "description" : "Card expires thru' year as a 4 digit integer: 2025, 2049."
          },
          "verification_code" : {
            "type" : "string",
            "required" : false,
            "description" : "Card verification number. Never stored. Only necessary if number_format is plain text"
          },
          "valid_from_month" : {
            "type" : "integer",
            "format" : "int32",
            "required" : false,
            "description" : "Card valid from month as an integer: January is 1, December is 12"
          },
          "valid_from_year" : {
            "type" : "integer",
            "format" : "int32",
            "required" : false,
            "description" : "Card valid from year as a 4 digit integer: 2025, 2049."
          }
        }
      } ]
    }
  }
}

CreditItem Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "CreditItem" : {
      "allOf": [
        {
          "$ref": "#/definitions/DocumentItem"
        },
        {
          "type": "object",
          "typeName": "CreditItem",
          "description": "A credit item. Supports custom properties",
          "properties": {
          }
        }
      ]
    }
  }
}

DebitCard Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "DebitCard" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentInstrument"
      }, {
        "type" : "object",
        "typeName" : "DebitCard",
        "description" : "Details of debitcard.",
        "properties" : {
          "card_number" : {
            "type" : "string",
            "required" : false,
            "description" : "Unmasked number or token representing the number. See property 'number_format'."
          },
          "card_number_format" : {
            "type" : "string",
            "required" : true,
            "description" : "Whether the 'number' property is plain text or is a token previously created by the payment provider",
            "enum" : [ "plain_text", "tokenized" ]
          },
          "expiration_month" : {
            "type" : "integer",
            "format" : "int32",
            "required" : false,
            "description" : "Card expires thru' month as an integer: January is 1, December is 12"
          },
          "expiration_year" : {
            "type" : "integer",
            "format" : "int32",
            "required" : false,
            "description" : "Card expires thru' year as a 4 digit integer: 2025, 2049."
          },
          "verification_code" : {
            "type" : "string",
            "required" : false,
            "description" : "Card verification number. Never stored. Only necessary if number_format is plain text"
          },
          "pin_number" : {
            "type" : "integer",
            "format" : "int32",
            "required" : false,
            "description" : "Debitcard pin number"
          }
        }
      } ]
    }
  }
}

Document Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "Document" : {
      "type" : "object",
      "typeName" : "Document",
      "description" : "Base class for order, invoice and credit. Supports custom properties",
      "x-extends": ["com.demandware.core.transport.data.CustomProperties"],
      "properties" : {
        "item_total" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The item total"
        },
        "item_subtotal" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The item subtotal"
        },
        "item_tax" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The item tax"
        },
        "shipping_total" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The total shipping cost"
        },
        "shipping_subtotal" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The subtotal shipping cost"
        },
        "shipping_tax" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The tax on shipping cost"
        },
        "price_adjustment_total" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The total price_adjustment."
        },
        "price_adjustment_subtotal" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The subtotal price_adjustments."
        },
        "price_adjustment_tax" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The tax on price_adjustments"
        },
        "fee" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The fee"
        },
        "total" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The total - this may differ to the transaction_total"
        },
        "subtotal" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The subtotal before tax calculation"
        },
        "tax" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The tax"
        }
      }
    }
  }
}

DocumentItem Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "DocumentItem" : {
      "type" : "object",
      "typeName" : "DocumentItem",
      "description" : "Base class for order, invoice and credit items. Supports custom properties",
      "x-extends": ["com.demandware.core.transport.data.CustomProperties"],
      "properties" : {
        "item_id" : {
          "type" : "string",
          "required" : true,
          "description" : "Identifies the item."
        },
        "name" : {
          "type" : "string",
          "required" : false,
          "description" : "The item name"
        },
        "quantity" : {
          "type" : "integer",
          "format" : "int32",
          "required" : true,
          "description" : "The quantity of item"
        },
        "unit_price" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The price per unit"
        },
        "item_price" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "The total price for the item"
        }
      }
    }
  }
}

Invoice Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "Invoice" : {
      "allOf": [
        {
          "$ref": "#/definitions/Document"
        },
        {
          "type": "object",
          "typeName": "Invoice",
          "description": "An invoice. Supports custom properties",
          "properties": {
            "invoice_id": {
              "type": "string",
              "required": true,
              "description": "Reference number of the invoice."
            },
            "shipping_address" : {
              "type" : "object",
              "description" : "Shipping address for the invoice.",
              "required" : false,
              "$ref" : "#/definitions/Address"
            },
            "billing" : {
              "type" : "object",
              "description" : "Billing information including contact data and address.",
              "required" : false,
              "$ref" : "#/definitions/BillingInformation"
            },
            "items" : {
              "type" : "array",
              "required" : false,
              "description" : "The items for this invoice.",
              "items": {
                "type": "object",
                "$ref" : "#/definitions/link/payment/InvoiceItem.json#/definitions/InvoiceItem"
              }
            }
          }
        }
      ]
    }
  }
}

InvoiceItem Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "InvoiceItem" : {
      "allOf": [
        {
          "$ref": "#/definitions/DocumentItem"
        },
        {
          "type": "object",
          "typeName": "InvoiceItem",
          "description": "An invoice item. Supports custom properties",
          "properties": {
            "order_item_id" : {
              "type" : "string",
              "required" : true,
              "description" : "Identifies the order item associated with this item"
            }
          }
        }
      ]
    }
  }
}

Order Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "Order" : {
      "allOf": [
        {
          "$ref": "#/definitions/Document"
        },
        {
          "type": "object",
          "typeName": "Order",
          "description": "An order. Supports custom properties",
          "properties": {
            "order_id": {
              "type": "string",
              "required": true,
              "description": "Reference number of the order."
            },
            "shipments" : {
              "type" : "array",
              "required" : false,
              "description" : "The shipments which belong to this order",
              "items": {
                "type": "object",
                "$ref" : "#/definitions/link/payment/Shipment.json#/definitions/Shipment"
              }
            },
            "items" : {
              "type" : "array",
              "required" : false,
              "description" : "The order items which belong to this order",
              "items": {
                "type": "object",
                "$ref" : "#/definitions/link/payment/OrderItem.json#/definitions/OrderItem"
              }
            }
          }
        }
      ]
    }
  }
}

OrderItem Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "OrderItem" : {
      "allOf": [
        {
          "$ref": "#/definitions/DocumentItem"
        },
        {
          "type": "object",
          "typeName": "OrderItem",
          "description": "An order item. Supports custom properties",
          "properties": {
            "shipment_id" : {
              "type" : "string",
              "required" : true,
              "description" : "Identifies the shipment associated with the item"
            },
            "product_id" : {
              "type" : "string",
              "required" : true,
              "description" : "Identifies the product referenced by the item"
            }
          }
        }
      ]
    }
  }
}

Payment Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "Payment" : {
      "type" : "object",
      "typeName" : "Payment",
      "properties" : {
        "holder_name" : {
          "type" : "string",
          "required" : false,
          "description" : "Full name of the payment owner - this may differ to the name in the billing address, if e.g. the credit card of a business is used."
        },
        "instrument" : {
          "type" : "object",
          "required" : false,
          "description" : "Payment instrument",
          "$ref" : "#/definitions/PaymentInstrument"
        }
      }
    }
  }
}

PaymentInstrument Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "PaymentInstrument" : {
      "type" : "object",
      "typeName" : "PaymentInstrument",
      "discriminator" : "$type",
      "required" : "$type",
      "description" : "Type specific payment instrument. Supports custom properties.",
      "x-extends": ["com.demandware.core.transport.data.CustomProperties"],
      "properties" : {
        "$type" : {
          "type" : "string"
        },
        "payment_method" : {
          "type" : "string",
          "required" : false,
          "description" : "The selected payment method as defined by the individual payment instrument. A payment card may e.g. accept values VISA, MASTERCARD"
        }
      }
    }
  }
}

Payment Transaction Request Contract

{
  "swagger": "2.0",
  "info": {
    "version": "99.9",
    "x-from": "1.0",
    "x-until": "99.9.1"
  },
  "definitions": {
    "PaymentTransactionRequest": {
      "type": "object",
      "typeName": "PaymentTransactionRequest",
      "description": "Basis for all request objects. Supports custom properties.",
      "x-extends": ["com.demandware.core.transport.data.CustomProperties"],
      "properties": {
        "customer_id": {
          "type": "string",
          "required": true,
          "description": "Human readable customer number."
        },
        "customer_ip": {
          "type": "string",
          "required": true,
          "description": "IP address of calling customer."
        },
        "customer_type" : {
          "type" : "string",
          "required" : true,
          "description" : "Type of customer, whether a guest, a new customer or an existing customer.",
          "enum" : [ "guest_customer", "new_customer", "existing_customer" ]
        },
        "idempotent_id": {
          "type": "string",
          "required": true,
          "description": "Identifies the request uniquely, remains unchanged over multiple retries of the same request."
        },
        "currency": {
          "type": "string",
          "required": true,
          "description": "The currency used for the payment capture as a ISO-4217 3-letter code such as USD, EUR."
        },
        "transaction_subtotal": {
          "type": "number",
          "format": "double",
          "required": true,
          "description": "The subtotal before tax calculation."
        },
        "transaction_tax": {
          "type": "number",
          "format": "double",
          "required": true,
          "description": "The tax included in transaction_total."
        },
        "transaction_fee": {
          "type": "number",
          "format": "double",
          "required": true,
          "description": "The fee included in transaction_total."
        },
        "transaction_total": {
          "type": "number",
          "format": "double",
          "required": true,
          "description": "The requested amount to be handled in this transaction. Set a transaction_total value in the response to override the requested value, otherwise this value is assumed."
        }
      }
    }
  }
}

PaymentTransactionResponse Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "PaymentTransactionResponse" : {
      "type" : "object",
      "typeName" : "PaymentTransactionResponse",
      "description" : "Base for all response classes. Supports custom properties. Custom properties written to the response are stored in the transaction and made available in later calls, for example custom properties written to an authorization response can be read from the authorization in the capture request. ",
      "x-extends" : [ "com.demandware.core.transport.data.CustomProperties" ],
      "properties" : {
        "transaction_id" : {
          "type" : "string",
          "required" : true,
          "description" : "Identifies the 3rd party transaction id."
        },
        "idempotent_id" : {
          "type" : "string",
          "required" : true,
          "description" : "Identifies the request uniquely, does not change for request retries."
        },
        "idempotent_status" : {
          "type" : "string",
          "required" : false,
          "description" : "Allows the response to indicate the idempotent state of the response. If no value is given, value PROCESSED is assumed. Return ALREADY_PROCESSED to indicate the response was already processed in an earlier request and this response is a copy of the earlier response.",
          "enum" : [ "processed", "already_processed" ]
        },
        "transaction_total" : {
          "type" : "number",
          "format" : "double",
          "required" : false,
          "description" : "The amount processed. This only needs to be specified if it differs from the request amount."
        },
        "date_time" : {
          "type" : "string",
          "format" : "datetime",
          "required" : false,
          "description" : "The timestamp for the transaction as set by the payment provider (ISO-8601 format yyyy-MM-dd'T'HH:mm:ssZ e.g. 2010-01-01T12:00:00+01:00)."
        },
        "result" : {
          "type" : "object",
          "required" : true,
          "description" : "The encapsulated transaction result",
          "$ref" : "#/definitions/ResponseResult"
        },
        "raw_response" : {
          "type" : "string",
          "required" : false,
          "description" : "Use this field to specify the raw data returned by a third party, made available for anaylsis."
        }
      }
    }
  }
}

ResponseResult Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "ResponseResult" : {
      "type" : "object",
      "typeName" : "ResponseResult",
      "properties" : {
        "status" : {
          "type" : "string",
          "required" : true,
          "description" : "Result of transaction, one of approved (transaction successfully completed), declined (transaction request was declined), pending (transaction successfully initialized but awaiting a followup call to approve or decline the request), error (request could not be completed due to a reported error)",
          "enum" : [ "approved", "declined", "pending", "error" ]
        },
        "description" : {
          "type" : "string",
          "required" : false,
          "description" : "The 3rd party specific description of the response result."
        },
        "code" : {
          "type" : "string",
          "required" : false,
          "description" : "The 3rd party specific response code."
        }
      }
    }
  }
}

Shipment Contract

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "Shipment" : {
      "type" : "object",
      "typeName" : "Shipment",
      "description" : "Order items can be grouped according to their shipping details. An order item identifies its ship group by id. Supports custom properties.",
      "x-extends": ["com.demandware.core.transport.data.CustomProperties"],
      "properties" : {
        "shipment_id" : {
          "type" : "string",
          "required" : true,
          "description" : "Identifies this shipment."
        },
        "first_name" : {
          "type" : "string",
          "required" : false,
          "description" : "First name of person receiving shipment."
        },
        "last_name" : {
          "type" : "string",
          "required" : false,
          "description" : "Last name of person receiving shipment."
        },
        "address" : {
          "type" : "object",
          "required" : false,
          "description" : "The shipping address",
          "$ref" : "#/definitions/Address"
        },
        "shipment_total" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "Total for the shipment."
        },
        "shipment_subtotal" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "Subtotal for the shipment."
        },
        "shipment_tax" : {
          "type" : "number",
          "format" : "double",
          "required" : true,
          "description" : "Tax for the shipment."
        }
      }
    }
  }
}

Related Links

Configure the B2C Commerce Processor

LINK Payment Provider

Sample API Transaction Contracts

Sample Code

X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.