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 below objects in each request depending on the request type.

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.

Payment Method object

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

Payment object

Field name Type Description
id string Payment id. It is an idempotent key, and will be used to identify the payment.
paymentNumber string Payment number.
amount number Payment amount.
currency string Payment currency.
softDescriptor string It is used to pass information related to the soft descriptor.
softDescriptorPhone string It is used to pass information related to the soft descriptor phone.

Refund object

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

Billing Account object

Field name Type Description
accountNumber string Account number.
currency string The default currency of the account.

Gateway Options object 

Field name Type Description
gatewayOptionsFields object Can be used to pass any information to the gateway using key-value pairs.

Response

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

HTTP codes

HTTP Code Description
200 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, indicated by the responseCode field in the response payload. Zuora will mark payment records as Processed or Error based on responseCode.
404 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.
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

Field name Type Description
responseCode string The payment status could be successful or failed, indicated by the responseCode field in the response payload. Zuora will mark payment records as Processed or Error based on responseCode.
  • Approved - Processed
  • Declined- Error
  • System- Error
gatewayResponseCode string

A response code received from a payment gateway.

Character limit: 20 
gatewayResponseMessage string

A response message received from a payment gateway.

Character limit: 255
gatewayTransactionId string

A reference id associated with a transaction.

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

A reference id associated with a transaction.

Character limit:  60 for the Validate call and 100 for Payment and Refund
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.

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"
}