Requests and responses processed by the payment hub
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 .
|
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" }