This describes the key data points exchanged as part of the Real Time status update PUSH call. The interface is a synchronous request/response message exchange initiated by GP2.0. The incoming transaction status update message is sent across to service hosted by the partners/clients that is expected to send a response back to GP2.0.
The table below describes all the data points available to be included in incoming instruction status update request. Each partner system can be set up to receive mutually agreed upon data points during the configuration stage of the service. By design, these fields are exposed to request templates used to generate external service payload and/or HTTP request path and query parameters. The fields are available as transaction, call-back, config, message and helper objects. The fields can be accessed using object/field notation in template.
This table contains all information needed about the incoming payment in order to notify about a status update.
|Data Type||Field Name||Description|
|Long||Id||Unique identifier assigned by GP2.0 to an incoming payment.|
|String||parentId||Is applicable only for refunds, the unique transaction id of the transaction against which refund is initiated|
|String||Reference||A unique Reference assigned to incoming payment|
|String||invoiceNumber||Invoice number against which this payment is made.|
|String||externalReference||External reference number|
|String||sellerDisplayName||Institution display name|
|String||payoutCurrency||The currency in which payment is to be made to institution|
|TransactionType||transactionType||CARD or RECEIVABLE|
|DealType||dealType||SALE or REFUND|
|BigDecimal||bookedAmount||Actual amount paid out to Partner/Client|
|String||buyerBusinessId||Business Id (Student Id)|
|String||buyerFirstName||Buyer first name|
|String||buyerLastName||Buyer last name|
|BigDecimal||paidOutAmount||Actual amount paid out to Partner/Client|
|String||paymentTypeId||Payment type ID, (refer to section 2.1.2 for definitions)|
|String||senderEmail||Sender email address|
|String||refundedCurrency||Currency in which refund is to be made|
|BigDecimal||refundedAmount||Amount refunded in student currency|
|BigDecimal||refundAmount||Total amount to be refunded (refund amount is university currency)|
|String||cardCurrency||Card currency (DCC transactions only)|
|DateTime||createdDate||Date pledge was created in GP2.0|
|DateTime||dueDate||Due date of the payment|
|DateTime||receivedDate||Date payment is received|
|DateTime||postedDate||Date the funds are booked to be sent to client|
|DateTime||authorisedDate||Date payment was authorised|
|DateTime||settlementDate||Settlement date (Refer to Glossary for definition)|
|DateTime||lastUpdatedDate||Last update time stamp|
|String||custom1 – custom 20||Payment can have up to 20 custom field as required by Client. These are string type fields which can contain any information defined by Client.|
The following table contains payment type ids and descriptions.
|BRL_WU_AGENT||Western Union Agent for Brazil||Offline|
|GEOSWIFTBANKTRANSFER||RMB Bank Transfer via Geoswift||Online|
|APOLLO_CREDIT_CARD||Apollo Credit Card (MCP)||Online|
|GEOSWIFTUNION PAY||UnionPay Card Payment||Online|
|APOLLONETBANKING||India Net Banking||Online|
|APOLLO_MYS_ONLINE||Malaysia Online Banking||Online|
|GEOSWIFT_HOSTED||Alipay, Unionpay, Wechat, RMB Bank Transfer *non-integrated clients only||Offline|
|CREDIT_CARD||DCC Credit Card||Online|
|WU_AGENT_INDIA||Western Union Agent for India||Offline|
|ICICI||ICICI Bank - INR Bank Transfer||Offline|
|CITIC||CITIC Bank - RMB Bank Transfer||Offline|
|HANA_BANK||Hana Bank- KRW Bank Transfer||Offline|
|CHINA_PAY_HOSTED||ChinaPay - RMB Bank Transfer via UnionPay||Online|
|GEOSWIFTUNIONPAYASIA||UnionPay Card Payment for Hong Kong and Japan||Online|
|CHINA_PAY_E_BANK||ChinaPay - RMB Bank Transfer||Online|
The callback information needs to contain the following fields:
|Data Type||Field Name||Description|
|String||url||The URL configured for the external service.|
|String||httpMethod||Http method to be used to call the service . Can be any of GET,PUT,POST or OTHER|
|Map||parameters||Configurable list of parameters.|
This table contains the information needed about the partner or client.
|Data Type||Field Name||Required?||Description|
|String||providerId||Mandatory||Unique identifier assigned to Partner/Client’s call back service|
|String||url||Optional, for web integration payments url can come from partner system||The URL configured for the external service|
|String||httpMethod||Optional, for web integration payments method can come from partner system||HTTP method to be used to call the service can be any of GET, PUT, POST or OTHER|
|boolean||isEnabled||Mandatory||Flag to indicate if the service is enabled|
|boolean||isSecured||Mandatory||Flag to indicate if service call would be made using a secure TLS channel.|
|String||userName||Optional||User name to call service|
|String||contentType||Mandatory||The response content type.|
|byte||payloadTemplate||Optional||Velocity template used to transform service payload.|
|byte||urlTemplate||Optional||Velocity template used to transform URL.|
|byte||inboundXsl||Mandatory||XSL to be used to transform response XML to canonical XML.|
|String||providerType||Mandatory||Provider type, SSO_ONLY or STANDARD|
|Set||invocationStates||Mandatory||Set of incoming payment Status change is to be sent to external service|
|boolean||isNonXmlResponse||Mandatory||Flag to indicate if the response will be a non XML , e.g plain text.|
|boolean||encryptionEnabled||Mandatory||Flag to indicate of encryption is enabled|
|String||encryptionKey||Optional||Encryption key used to encrypt out going payload|
|String||encryptionMethod||Optional||Encryption method used|
|boolean||hashEnabled||Mandatory||Is hashing enabled|
|String||hashAlgorithm||Optional||Hash Algorithm to be used|
|String||hashSecretKey||Optional||Hash secret key|
- A REST Service End-point is required to accept Convera callback and needs to be developed by our partner/client.
- Specific status and transaction details would need to be subscribed to via the end-point. Please provide your specifications to Convera.
- Please provide a mapping table should you need to transcode callback statuses.
- See security option in Technical Interface section below
The status update services can be invoked using GET, POST or OTHER http methods. The request object is created using velocity templates. For GET request, a URL template is used to generate URL containing data as HTTP request query or path paraments.
The Payload template is used when invocation method is POST and OTHER. In this case, both URL and Payload templates are used to create request object for partners.
If a GET method is used to call external service, the update request data is transported as query or path parameters. A velocity template can be configured to append parameters to service URL.
To invoke external service using POST or OTHER method, the update request data is transported as request payload. A velocity template can be configured to output a payload, which could be in any form acceptable to partner service.
In POST and OTHER method configuration, first URL template is applied to create a URL and then a Payload template is applied to create request payload.
The external partner’s service can send any text or XML response back. The response is valid if it can be transformed, by applying an XSL based transformer, to canonical XML message format. Although there are no strictly defined data points requirements, it is expected to contain data to convey following logical semantics:
- Result of the call. Success or Failure. On failure response, we retry to send same request to partner system’s API
up to 5 times in quick succession. If it fails, contact your Account Representative at Convera.
- A code corresponding to result.
- An optional message describing error or successful execution.
The configured inbound XSL template should be able convert this response in to a canonical XML message. The schema is given in the next section.
The response is transformed to an XML canonical message, which can be converted to a Java object for further logging and auditing.
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" xmlns:tns="http://bp.globalpay.wu.com/realtime" targetNamespace="http://bp.globalpay.wu.com/realtime" elementFormDefault="qualified" attributeFormDefault="unqualified" vc:minVersion="1.1"> <xs:element name="realTimeCallbackResponse" type="tns:RealTimeCallbackResponse"/> <xs:complexType name="RealTimeCallbackResponse"> <xs:sequence> <xs:element name="success" type="xs:boolean" minOccurs="1" maxOccurs="1"/> <xs:element name="errorCode" type="xs:string" minOccurs="0" maxOccurs="1"/> <xs:element name="retry" type="xs:boolean" minOccurs="0" maxOccurs="1"/> <xs:element name="narrative" type="xs:string" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:schema>
Following is sample response received from a mock external service.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <statusUpdateResponse> <responseCode>200</responseCode> <responseMessage>Updated Successfully</responseMessage> <transactionId>100000002895</transactionId> </statusUpdateResponse>
If the response is not in XML format, it is wrapped in an XML document. The response received is inserted in the document between “” and “</ data>” tags.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <nonXmlResponse> <data>response data</data> </nonXmlResponse>
The configured inbound XSL is used to transform XML incoming response to another XML, conforming to Canonical XML Message schema. An example XSL stylesheet is listed below. This XSL which when applied to sample response above, would generate a Canonical XML Message.
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="xml" encoding="utf-8" indent="no"/> <xsl:template match="/"> <realTimeCallbackResponse xmlns="http://bp.globalpay.wu.com/realtime"> <xsl:variable name="code"> <xsl:value-of select="//mockStatusUpdateResponse/responseCode"/> </xsl:variable> <xsl:choose> <xsl:when test="$code = '200'"> <success>true</success> </xsl:when> <xsl:otherwise> <success>false</success> </xsl:otherwise> </xsl:choose> <errorCode> <xsl:value-of select="$code"/> </errorCode> <narrative> <xsl:value-of select="//mockStatusUpdateResponse/responseMessage"/> </narrative> </realTimeCallbackResponse> </xsl:template> </xsl:stylesheet>
This section describes the technical interface for the Real Time Call Back service.
The MEP will be based on a synchronous request/response invocation instigated by the GP2.0 platform to a service hosted by the financial institution (FI).
The invocation will be made over HTTPS/TLS 1.2, where the request payload will be sent as an HTTP POST with the content type set to application/xml. The response is required to have the content type application/xml.
Security will be based on HTTP(S) BASIC authentication as described by RFC 2617 (http://tools.ietf.org/html/rfc2617).
- Hash : Verification of authenticity and also detection of information tempering in the request is done using hash based message authentication method. The hash code is computed using SHA-1
- Login/Password: to secure the callback via login and password. Although it will be standard callback model with fixed URL.
- Encryption: Encryption hash could be SHA-256, or SHA-512. Should you have some specific needs, additional providers can be implemented to meet your needs. There is no fundamental change required in the basic implementation of the functionality.
Updated 4 days ago