Data Definition

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 TypeField NameDescription
LongIdUnique identifier assigned by GP2.0 to an incoming payment.
StringparentIdIs applicable only for refunds, the unique transaction id of the transaction against which refund is initiated
StringReferenceA unique Reference assigned to incoming payment
StringinvoiceNumberInvoice number against which this payment is made.
StringexternalReferenceExternal reference number
LongsellerIdPartner ID
StringsellerNameInstitution name
StringsellerDisplayNameInstitution display name
StringsellerCountryInstitution country
StringpayoutCurrencyThe currency in which payment is to be made to institution
StringStatusPayment status
TransactionTypetransactionTypeCARD or RECEIVABLE
DealTypedealTypeSALE or REFUND
BigDecimalbookedAmountActual amount paid out to Partner/Client
StringbuyerBusinessIdBusiness Id (Student Id)
StringbuyerFirstNameBuyer first name
StringbuyerLastNameBuyer last name
StringbuyerEmailBuyer email
BigDecimalpaidOutAmountActual amount paid out to Partner/Client
StringpaymentTypeIdPayment type ID, (refer to section 2.1.2 for definitions)
StringsenderNameSender name
StringsenderEmailSender email address
StringrefundedCurrencyCurrency in which refund is to be made
BigDecimalrefundedAmountAmount refunded in student currency
BigDecimalrefundAmountTotal amount to be refunded (refund amount is university currency)
StringcardCurrencyCard currency (DCC transactions only)
DateTimecreatedDateDate pledge was created in GP2.0
DateTimedueDateDue date of the payment
DateTimereceivedDateDate payment is received
DateTimepostedDateDate the funds are booked to be sent to client
DateTimeauthorisedDateDate payment was authorised
DateTimesettlementDateSettlement date (Refer to Glossary for definition)
DateTimelastUpdatedDateLast update time stamp
Stringcustom1 – custom 20Payment 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 TypeDescriptionOnline/Offline
BRL_WU_AGENTWestern Union Agent for BrazilOffline
GEOSWIFTBANKTRANSFERRMB Bank Transfer via GeoswiftOnline
APOLLO_CREDIT_CARDApollo Credit Card (MCP)Online
APOLLOSOFORTSofortOnline
APOLLOPOLIPoliOnline
APOLLOIDEALiDEALOnline
APOLLOTRUSTLYTrustlyOnline
GEOSWIFTALI PAYAlipayOnline
GEOSWIFTUNION PAYUnionPay Card PaymentOnline
APOLLONETBANKINGIndia Net BankingOnline
APOLLO_MYS_ONLINEMalaysia Online BankingOnline
APOLLO_BRA_ONLINEBoletoOnline
GEOSWIFT_WECHAT_PAYWeChat PayOnline
WIREBank TransferOffline
GEOSWIFT_HOSTEDAlipay, Unionpay, Wechat, RMB Bank Transfer *non-integrated clients onlyOffline
CREDIT_CARDDCC Credit CardOnline
WU_AGENT_INDIAWestern Union Agent for IndiaOffline
ICICIICICI Bank - INR Bank TransferOffline
CITICCITIC Bank - RMB Bank TransferOffline
HANA_BANKHana Bank- KRW Bank TransferOffline
CHINA_PAY_HOSTEDChinaPay - RMB Bank Transfer via UnionPayOnline
GEOSWIFTUNIONPAYASIAUnionPay Card Payment for Hong Kong and JapanOnline
CHINA_PAY_E_BANKChinaPay - RMB Bank TransferOnline

Call Back Information

The callback information needs to contain the following fields:

Data TypeField NameDescription
StringurlThe URL configured for the external service.
StringhttpMethodHttp method to be used to call the service . Can be any of GET,PUT,POST or OTHER
MapparametersConfigurable list of parameters.

Real Time Call Back Provider Configuration

This table contains the information needed about the partner or client.

Data TypeField NameRequired?Description
StringproviderIdMandatoryUnique identifier assigned to Partner/Client’s call back service
StringurlOptional, for web integration payments url can come from partner systemThe URL configured for the external service
StringhttpMethodOptional, for web integration payments method can come from partner systemHTTP method to be used to call the service can be any of GET, PUT, POST or OTHER
booleanisEnabledMandatoryFlag to indicate if the service is enabled
booleanisSecuredMandatoryFlag to indicate if service call would be made using a secure TLS channel.
StringuserNameOptionalUser name to call service
StringpasswordOptionalPassword used
StringcontentTypeMandatoryThe response content type.
byte[]payloadTemplateOptionalVelocity template used to transform service payload.
byte[]urlTemplateOptionalVelocity template used to transform URL.
byte[]inboundXslMandatoryXSL to be used to transform response XML to canonical XML.
StringproviderTypeMandatoryProvider type, SSO_ONLY or STANDARD
SetinvocationStatesMandatorySet of incoming payment Status change is to be sent to external service
booleanisNonXmlResponseMandatoryFlag to indicate if the response will be a non XML , e.g plain text.
booleanencryptionEnabledMandatoryFlag to indicate of encryption is enabled
StringencryptionKeyOptionalEncryption key used to encrypt out going payload
StringencryptionMethodOptionalEncryption method used
booleanhashEnabledMandatoryIs hashing enabled
StringhashAlgorithmOptionalHash Algorithm to be used
StringhashSecretKeyOptionalHash secret key

NOTE:

  1. A REST Service End-point is required to accept Convera callback and needs to be developed by our partner/client.
  2. Specific status and transaction details would need to be subscribed to via the end-point. Please provide your specifications to Convera.
  3. Please provide a mapping table should you need to transcode callback statuses.
  4. 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:

  1. 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
  2. Login/Password: to secure the callback via login and password. Although it will be standard callback model with fixed URL.
  3. 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.

Did this page help you?