Skip to main content

Requests and responses processed by the payment hub

Zuora

Requests and responses processed by the payment hub

  1. Last updated
  2. Save as PDF

This article describes the requests and responses that are processed by the payment hub and provides a few examples for your reference.

The transaction attempts through the payment hub will be timed out if the following limits are reached:

  • 30 seconds for establishing a connection to the payment hub
  • 60 seconds for receiving the response from the payment hub after the connection is established

Request

Zuora includes the following objects in each request depending on the request type:

  • For the payment request, the payment, paymentMethod, and billingAccount objects are included. The gatewayOptions object is optional.
  • For the refund request, the refund, paymentMethod, and billingAccount objects are included. The gatewayOptions object is optional.
  • For the payment method validation request, the paymentMethod object is included. The billingAccount and gatewayOptions objects are optional.
Object name  Description
paymentMethod Include fields related to the payment method.
payment Include fields related to the payment.
refund Include fields related to the refund.
billingAccount Include fields related to the billing account.
gatewayOptions Can be used to pass any information to the gateway using key-value pairs.

For the payment request, refund request, and payment method validation request, the POST method is used as the HTTP method.

Payment Method object

Field name Type Description Mandatory in request
id string Payment method Id. Y
type string Payment method type. Only the custom payment method type is supported by UPC and OPM. Y
upcTokenData object Custom payment method type fields. Y

Payment object

Field name Type Description Mandatory in request
id string Payment id. It is an idempotent key, and will be used to identify the payment. Y
paymentNumber string Payment number. Y
amount number Payment amount. Y
currency string Payment currency. Y
softDescriptor string It is used to pass information related to the soft descriptor, which is the information that appears on the statement to distinguish the payment. Usually it is a static descriptor labeling the merchant. It is recommended to keep it as short and descriptive as possible because complexity can increase chargeback rates. N
softDescriptorPhone string It is used to pass information related to the soft descriptor phone. N

Refund object

Field name Type Description Mandatory in request
id string Refund id. It is an idempotent key, and will be used to identify Refund. Y
refundNumber string Refund number. Y
amount number Refund amount. Y
paymentId string Payment id. It is an idempotent key, and will be used to identify payment associated with refund. Y
referenceId string Reference id provided in response to associated payment. Y
softDescriptor string It is used to pass information related to the soft descriptor. N
softDescriptorPhone string It is used to pass information related to the soft descriptor phone. N

Billing Account object

Field name Type Description Mandatory in request
accountNumber string Account number. Y
currency string The default currency of the account. Y

Gateway Options object 

Field name Type Description Mandatory in request
gatewayOptions object Can be used to pass any information to the gateway using key-value pairs. N

Response

Zuora expects the combination of the below HTTP codes and payment hub response field in response to a request.

HTTP codes

The HTTP code is also presented in the Response_Code field in the transaction log.

HTTP Code Description
200/202

The HTTP request is received by an external server (a payment hub), and the payment is successfully sent to the external gateway and a response is already received from the gateway side.

The payment status could be successful or failed, determined by the responseCode field in Response_Body. Zuora will mark payment records as Processed or Error based on responseCode.

For details, see Payment hub response field.
400 The HTTP request is received by an external server (a payment hub), passed authentication, but the payment hub cannot understand it, or cannot find some important information. The payment request is not sent to an external gateway. Zuora will mark payment records as Error status.
401 The HTTP request is received by an external server (a payment hub), and can not pass authentication. The payment request is not sent to an external gateway. Zuora will mark payment records as Error status.
Other code such as 404, 500 Something is wrong on the external server (a payment hub) side. The payment hub does not know if the payment record has been sent to an external gateway. The payment status is unknown. Zuora will keep payment records as Processing status and response fields will be ignored.

Payment hub response field

For HTTP code 200/202, the payment hub returns the Response_Body field. In Response_Body, though only the responseCode field is required, it is recommended that the payment hub can provide as many fields in the following table as possible.

Field name Type Description Required in response from the payment hub
Response_Body
responseCode string

If HTTP code 200/202 is returned, the payment status is determined by the value of  responseCode, including Approved, Declined, System and Failed. Zuora will mark payment records as Processed or Error based on responseCode.

  • Approved - Processed
  • Declined - Error
  • System - Error
  • Failed - Error

Yes
gatewayResponseCode string

A response code received from a payment gateway.

Character limit: 20 

 No
gatewayResponseMessage string

A response message received from a payment gateway.

Character limit: 255

 No
gatewayTransactionId string

A reference id associated with a transaction.

Character limit:  60 for the Validate call and 100 for Payment and Refund

 No
gatewaySecondTransactionId string

A reference id associated with a transaction.

Character limit:  60 for the Validate call and 100 for Payment and Refund

 No
upcTokenData object Custom payment method type fields. It will be updated if it is included in the response. It is only supported in case of Validate and Payment. No

Examples

Here are three examples for the Payment Method, Payment, and Refund objects.

Payment Method object

Request 
{
    "billingAccount": {
        "accountNumber": "A-1621965929897",
        "currency": "USD"
    },
    "operation": "Validate",
    "paymentGatewayName": "UPCTokenGateway1621965929867",
    "paymentMethod": {
        "authAmount": "1",
        "currency": "USD",
        "type": "AmazonPay__c_12368",
        "upcTokenData": {
            "AmazonAccount": "SampleAmazonAccount",
            "AmazonToken": "3sample54cf04113e3f1595951874003",
            "AmazonTokenType": "Digital",
            "ShopperEmail": "sample@testmail.com",
            "ShoppingDate": ""
        }
    }, 
    "tenantId": "12368"
}
Response (HTTP code: 200)
{
    "gatewayResponseCode": "601",
    "gatewayResponseMessage": "The transaction has been approved.",
    "gatewaySecondTransactionId": "735788334",
    "gatewayTransactionId": "383315250",
    "responseCode": "Approved",
    "upcTokenData": "{ \"ShopperEmail\": \"sample@testmail.com\"}"
}

Payment object

Request
{
    "billingAccount": {
        "accountNumber": "A00000004",
        "currency": "USD"
    },
    "operation": "Payment",
    "payment": {
        "amount": "200",
        "currency": "USD",
        "id": "4028818579a43c3f0179aba917410419",
        "paymentNumber": "P-00000011"
    },
    "paymentGatewayName": "UPC_Token",
    "paymentMethod": {
        "id": "4028818579a43c3f0179aba2808103e8",
        "type": "AmazonPay__c_12368",
        "upcTokenData": {
            "AmazonAccount": "SampleAmazonAccount",
            "AmazonToken": "3sample54cf04113e3f1595951874003",
            "AmazonTokenType": "Digital",
            "ShopperEmail": "sample@testmail.com",
            "ShoppingDate": ""
        }
    },
    "tenantId": "12368"
}
Response  (HTTP code: 200)
{
    "gatewayResponseCode": "601",
    "gatewayResponseMessage": "The transaction has been approved.",
    "gatewaySecondTransactionId": "20998810",
    "gatewayTransactionId": "180404672",
    "responseCode": "Approved",
    "upcTokenData": "{ \"ShopperEmail\": \"sample@testmail.com\"}"
}

Refund object

Request 
{
    "billingAccount": {
        "accountNumber": "A00000004",
        "currency": "USD"
    },
    "operation": "Refund",
    "paymentGatewayName": "UPC_Token",
    "paymentMethod": {
        "id": "4028818579a43c3f0179aba2808103e8",
        "type": "AmazonPay__c_12368",
        "upcTokenData": {
            "AmazonAccount": "SampleAmazonAccount",
            "AmazonToken": "3sample54cf04113e3f1595951874003",
            "AmazonTokenType": "Digital",
            "ShopperEmail": "sample@testmail.com",
            "ShoppingDate": ""
        }
    },
    "refund": {
        "amount": "200",
        "id": "4028818579a43c3f0179aba6ebfb040d",
        "paymentId": "4028818579a43c3f0179aba2b14a03ea",
        "referenceId": "166435652",
        "refundNumber": "R-00000005"
    },
    "tenantId": "12368"
}
Response (HTTP code: 200)
{
    "gatewayResponseCode": "601",
    "gatewayResponseMessage": "The transaction has been approved.",
    "gatewaySecondTransactionId": "687106060",
    "gatewayTransactionId": "760690295",
    "responseCode": "Approved"
}