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.

Request Definition

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.

Transaction Details

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
Long	sellerId	Partner ID
String	sellerName	Institution name
String	sellerDisplayName	Institution display name
String	sellerCountry	Institution country
String	payoutCurrency	The currency in which payment is to be made to institution
String	Status	Payment status
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
String	buyerEmail	Buyer email
BigDecimal	paidOutAmount	Actual amount paid out to Partner/Client
String	paymentTypeId	Payment type ID, (refer to section 2.1.2 for definitions)
String	senderName	Sender name
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.

Payment Type Id

The following table contains payment type ids and descriptions.

Payment Type	Description	Online/Offline
BRL_WU_AGENT	Western Union Agent for Brazil	Offline
GEOSWIFTBANKTRANSFER	RMB Bank Transfer via Geoswift	Online
APOLLO_CREDIT_CARD	Apollo Credit Card (MCP)	Online
APOLLOSOFORT	Sofort	Online
APOLLOPOLI	Poli	Online
APOLLOIDEAL	iDEAL	Online
APOLLOTRUSTLY	Trustly	Online
GEOSWIFTALI PAY	Alipay	Online
GEOSWIFTUNION PAY	UnionPay Card Payment	Online
APOLLONETBANKING	India Net Banking	Online
APOLLO_MYS_ONLINE	Malaysia Online Banking	Online
APOLLO_BRA_ONLINE	Boleto	Online
GEOSWIFT_WECHAT_PAY	WeChat Pay	Online
WIRE	Bank Transfer	Offline
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

Call Back Information

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.

Real Time Call Back Provider Configuration

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	password	Optional	Password used
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

NOTE:

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

Request Templates

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.

URL Template

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.

Payload Template

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.

Response Definition

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.

Canonical XML Message Schema

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>

Sample Response

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>

Sample Inbound XSL Stylesheet

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>

Technical Interface

This section describes the technical interface for the Real Time Call Back service.

Message Exchange Pattern (MEP)

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).

Transport Protocol

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

Security will be based on HTTP(S) BASIC authentication as described by RFC 2617 (http://tools.ietf.org/html/rfc2617).

Options:

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.