Sample API Transaction Contracts

API contracts provide the fields that must be populated for the API transaction request and responses. These contract examples address each contract type. Within each of the samples, the API helper contracts are specified with "$ref", such as "$ref" : "#/definitions/PaymentTransactionRequest".

Authorization Request

 {
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "AuthorizeRequest" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionRequest"
      }, {
        "type" : "object",
        "typeName" : "AuthorizeRequest",
        "description" : "A request for an authorization.",
        "properties" : {
          "billing" : {
            "type" : "object",
            "description" : "Billing information related to this request.",
            "required" : false,
            "$ref" : "#/definitions/BillingInformation"
          },
          "payment" : {
            "type" : "object",
            "description" : "Payment related to this request.",
            "required" : false,
            "$ref" : "#/definitions/Payment"
          },
          "order" : {
            "type" : "object",
            "required" : false,
            "$ref" : "#/definitions/Order"
          }
        }
      } ]
    }
  }
}

Authorization Response

 {
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "AuthorizeResponse" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionResponse"
      }, {
        "type" : "object",
        "typeName" : "AuthorizeResponse",
        "properties" : {
          "tokenized_payment_instrument" : {
            "type" : "string",
            "required" : false,
            "description" : "The tokenized card number. This should be specified if the 3rd party is responsible for tokenizing the card number and needs it in a followup call."
          }
        }
      } ]
    }
  }
}

Sale Request

   {
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "SaleRequest" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionRequest"
      }, {
        "type" : "object",
        "typeName" : "SaleRequest",
        "description" : "Sale request object encapsulates payment details",
        "properties" : {
          "billing" : {
            "type" : "object",
            "required" : false,
            "$ref" : "#/definitions/BillingInformation"
          },
          "payment" : {
            "type" : "object",
            "required" : false,
            "$ref" : "#/definitions/Payment"
          },
          "order" : {
            "type" : "object",
            "required" : false,
            "$ref" : "#/definitions/Order"
          },
          "authorize_response" : {
            "type" : "object",
            "required" : false,
            "description" : "When available, the successful response to the last previous authorize request.",
            "$ref" : "#/definitions/AuthorizeResponse"
          }
        }
      } ]
    }
  }
}

Sale Response

  {
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "SaleResponse" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionResponse"
      }, {
        "type" : "object",
        "typeName" : "SaleResponse",
        "properties" : {
          "tokenized_payment_instrument" : {
            "type" : "string",
            "required" : false,
            "description" : "The tokenized card number. This should be specified if the 3rd party is responsible for tokenizing the card number and needs it in a followup call."
          }
        }
      } ]
    }
  }
}

Capture Request

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "CaptureRequest" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionRequest"
      }, {
        "type" : "object",
        "typeName" : "CaptureRequest",
        "description" : "Request to capture a previous authorization. The request provides the authorization response and lists any previous successful capture responses.",
        "properties" : {
          "authorize_response" : {
            "type" : "object",
            "description" : "Authorize response.",
            "required" : false,
            "$ref" : "#/definitions/AuthorizeResponse"
          },
          "previous_captures" : {
            "type" : "array",
            "description" : "Previous successful capture responses.",
            "required" : false,
            "items": {
              "type": "object",
              "$ref" : "#/definitions/link/payment/Capture.json#/definitions/CaptureResponse"
            }
          },
          "invoice" : {
            "type" : "object",
            "description" : "Invoice assigned to this capture request.",
            "required" : false,
            "$ref" : "#/definitions/Invoice"
          }
        }
      } ]
    }
  }
}

Capture Response

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "CaptureResponse" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionResponse"
      }, {
        "type" : "object",
        "typeName" : "CaptureResponse",
        "properties" : { }
      } ]
    }
  }
}

Refund Request

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "RefundRequest" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionRequest"
      }, {
        "type" : "object",
        "typeName" : "RefundRequest",
        "description" : "A request to refund one or more previous captures or sales. The request also contains information about the invoices and / or credits related to the payment.",
        "properties" : {
          "previous_captures" : {
            "type" : "array",
            "description" : "Previous successful capture responses.",
            "required" : false,
            "items": {
              "type": "object",
              "$ref" : "#/definitions/link/payment/Capture.json#/definitions/CaptureResponse"
            }
          },
          "previous_sales" : {
            "type" : "array",
            "description" : "Previous successful sale responses.",
            "required" : false,
            "items": {
              "type": "object",
              "$ref" : "#/definitions/link/payment/Sale.json#/definitions/SaleResponse"
            }
          },
          "invoices" : {
            "type" : "array",
            "description" : "Invoices related to this payment.",
            "required" : false,
            "items": {
              "type": "object",
              "$ref" : "#/definitions/link/payment/Invoice.json#/definitions/Invoice"
            }
          },
          "credits" : {
            "type" : "array",
            "description" : "Credits related to this payment.",
            "required" : false,
            "items": {
              "type": "object",
              "$ref" : "#/definitions/link/payment/Credit.json#/definitions/Credit"
            }
          },
          "payment" : {
            "type" : "object",
            "description" : "Payment related to this request.",
            "required" : false,
            "$ref" : "#/definitions/Payment"
          },
          "selected_capture_transaction_id" : {
            "type" : "string",
            "required" : true,
            "description" : "Indicates which of the previous_captures or previous_sales is to be refunded by providing the matching transaction_id."
          }
        }
      } ]
    }
  }
}

Refund Response

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "RefundResponse" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionResponse"
      }, {
        "type" : "object",
        "typeName" : "RefundResponse",
        "properties" : { }
      } ]
    }
  }
}

Void Request

{
    "customer_id": "customerNr123",
    "customer_ip": "123.223.114.225",
    "idempotent_id": "12345_idempotent_id_12345",
    "currency": "EUR",
    "transaction_subtotal": 0.00,
    "transaction_tax": 0.00,
    "transaction_total": 25.25,
    "previous_capture_to_void": {
    },
    "previous_sale_to_void": {
    },
    "previous_authorize_to_void": {
        "result": {
            "status": "approved",
            "description": "All good"
        },
        "transaction_total": 85.04,
        "transaction_id": "5175184016786036304009"
    },
    "payment": {
        "holder_name": "Angela Merkel",
        "instrument": {
            "$type": "credit_card",
            "card_number": "thisisatoken",
            "card_number_format": "tokenized",
            "verification_cod{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "VoidPaymentRequest" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionRequest"
      }, {
        "type" : "object",
        "typeName" : "VoidPaymentRequest",
        "description" : "Cancel the entire payment. The request includes details of the capture and auth response, or sale response to be voided",
        "properties" : {
          "payment" : {
            "type" : "object",
            "description" : "Payment related to this request.",
            "required" : false,
            "$ref" : "#/definitions/Payment"
          },
          "previous_capture_to_void" : {
            "type" : "object",
            "description" : "Capture response to be voided.",
            "required" : false,
            "$ref" : "#/definitions/CaptureResponse"
          },
          "previous_sale_to_void" : {
            "type" : "object",
            "description" : "Sale response to be voided.",
            "required" : false,
            "$ref" : "#/definitions/SaleResponse"
          },
          "previous_authorize_to_void" : {
            "type" : "object",
            "description" : "Authorize response to be voided.",
            "required" : false,
            "$ref" : "#/definitions/AuthorizeResponse"
          }
        }
      } ]
    }
  }
}

Void Response

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "VoidPaymentResponse" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionResponse"
      }, {
        "type" : "object",
        "typeName" : "VoidPaymentResponse",
        "properties" : { }
      } ]
    }
  }
}

Credit Request

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "CreditRequest" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionRequest"
      }, {
        "type" : "object",
        "typeName" : "CreditRequest",
        "description" : "Request an adhoc credit",
        "properties" : {
          "billing" : {
            "type" : "object",
            "description" : "Billing information related to this request.",
            "required" : false,
            "$ref" : "#/definitions/BillingInformation"
          },
          "payment" : {
            "type" : "object",
            "description" : "Payment related to this request.",
            "required" : false,
            "$ref" : "#/definitions/Payment"
          }

        }
      } ]
    }
  }
}

Credit Response

{
  "swagger" : "2.0",
  "info" : {
    "version" : "99.9",
    "x-from" : "1.0",
    "x-until" : "99.9.1"
  },
  "definitions" : {
    "CreditResponse" : {
      "allOf" : [ {
        "$ref" : "#/definitions/PaymentTransactionResponse"
      }, {
        "type" : "object",
        "typeName" : "CreditResponse",
        "properties" : {
          "tokenized_payment_instrument" : {
            "type" : "string",
            "required" : false,
            "description" : "The tokenized card number. This should be specified if the 3rd party is responsible for tokenizing the card number and needs it in a followup call."
          }
        }
      } ]
    }
  }
}

Related Links

Configure the B2C Commerce Processor

LINK Payment Provider

Sample API Helper 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.