3 Using the Thredd Web Services API
This section provides an overview of how to use the Thredd web services to register customers for Agency Banking and create cards with Agency Banking features enabled. This is a three-step process:
Each of the above steps is described in further details below. For more detailed information, refer to the Web Services Guide.
Once the account is set up, you can use the web services for additional actions on the account, such as Making External Payments.
3.1 Step 1: Registering a Customer for Agency Banking
API: Ws_Banking_CreateCustomer
You must first register the customer prior to creating a card with bank-enabled features. This web service enables you to register customer details. For details of the web service fields, see the Web Services Guide.
See the example code snippets below.
Request
<Ws_Banking_CreateCustomer xmlns="http://www.globalprocessing.ae/HyperionWeb">
<request>
<WSID>2021123456789</WSID>
<IssCode>PMT</IssCode>
<CardDesign>Crd001</CardDesign>
<Associates>
<Associate>
<applicant>Y</applicant>
<dateOfBirth>01041995</dateOfBirth>
<documentInfo xsi:nil="true" />
<email>joe.bloggs@gmail.com</email>
<firstName>Joe</firstName>
<middleName></middleName>
<lastName>Bloggs</lastName>
<ownership>1</ownership>
<phone>+441223345678</phone>
<type>INDIVIDUAL</type>
<homeAddress>
<addressLine1>21</addressLine1>
<addressLine2>Test lane</addressLine2>
<posttown>Test Town</posttown>
<postCode>CB24 0GE</postCode>
<country>UK</country>
</homeAddress>
</Associate>
</Associates>
<DocumentInfo>
<DocumentInfo>
<filename></filename>
<filepath></filepath>
<uploadDate></uploadDate>
</DocumentInfo>
</DocumentInfo>
<ExpectedMonthlySpend>1000</ExpectedMonthlySpend>
<ExternalReference></ExternalReference>
<IndustryCode></IndustryCode>
<RegisteredAddress>
<addressLine1></addressLine1>
<addressLine2></addressLine2>
<posttown></posttown>
<postCode></postCode>
<country></country>
</RegisteredAddress>
<TCSVersion>1</TCSVersion>
<TradingAddress>
<addressLine1></addressLine1>
<addressLine2></addressLine2>
<posttown></posttown>
<postCode></postCode>
<country></country>
</TradingAddress>
<Type>INDIVIDUAL</Type>
<Name></Name>
<CompanyRegNumber></CompanyRegNumber>
</request>
</Ws_Banking_CreateCustomer>
Thredd card product to use: <CardDesign>Crd001</CardDesign>
Notes
-
You can provide details of the customer using the fields in the
<Associate>group. -
If the account
<Type>is for an INDIVIDUAL all fields relating to a company or business can be left blank (e.g.,<TradingAddress>,<IndustryCode>,<CompanyRegNumber>). -
The following fields are mandatory:
<CardDesign>,<Associates>,<ExpectedMonthlySpend>,<TCSVersion>and<Type>. Other fields are optional or conditional, depending on the<Type>of customer.
The functionality to upload supporting documents using the <DocumentInfo> group fields is reserved for Modulr Direct customers and is not available to customers connecting via Thredd.
Response
Below is an example of the response returned by Thredd.
<Ws_Banking_CreateCustomerResponse xmlns="http://www.globalprocessing.ae/HyperionWeb">
<Ws_Banking_CreateCustomerResult>
<WSID>2021123456789</WSID>
<IssCode>PMT</IssCode>
<ActionCode>000</ActionCode>
<CustomerID>C123456</CustomerID>
<Messages>
<BankingError>
<field></field>
<code></code>
<message></message>
<error></error>
</BankingError>
</Messages>
</Ws_Banking_CreateCustomerResult>
</Ws_Banking_CreateCustomerResponse>
Notes
-
A successful response returns an
<ActionCode>of 000. -
A successful response returns a
<CustomerID>, which is a unique identifier for the newly registered customer. This must be used in all subsequent web service requests relating to this customer. -
If there is an error, the
<ActionCode>and<Messages>section can provide further details.
3.2 Step 2: Creating a Card with Agency Banking
API: Ws_CreateCard_V2
This web service creates a card which has a bank account linked to it, with Agency Banking features enabled. It will also upgrade an existing card to have banking features. For details of the web service fields, see the Web Services Guide.
Before using this web service, use Ws_Banking_CreateCustomer to register the customer and obtain the unique CustomerID. See Step 1: Registering a Customer for Agency Banking.
See the example code snippets below.
Request
<hyp:Ws_CreateCard_V2>
<hyp:request>
<hyp:WSID>2021123456789</hyp:WSID>
<hyp:IssCode>PMT</hyp:IssCode>
<hyp:TxnCode>10</hyp:TxnCode>
<hyp:clientCode></hyp:clientCode>
<hyp:Title>Mr</hyp:Title>
<hyp:LastName>Bloggs</hyp:LastName>
<hyp:FirstName>Joe</hyp:FirstName>
<hyp:Addrl1>Office 13, Telfords Yard</hyp:Addrl1>
<hyp:City>London</hyp:City>
<hyp:Postcode>E1W 2BS</hyp:Postcode>
<hyp:ISOCountryCode>826</hyp:ISOCountryCode>
<hyp:Mobile>+447736123456</hyp:Mobile>
<hyp:PublicToken></hyp:PublicToken>
<hyp:CardDesign>123</hyp:CardDesign>
<hyp:ExternalRef></hyp:ExternalRef>
<hyp:DateOfBirth></hyp:DateOfBirth>
<hyp:AccCode>123456</hyp:AccCode>
<hyp:LocDate>2021-01-01</hyp:LocDate>
<hyp:LocTime>120000</hyp:LocTime>
<hyp:TerminalID></hyp:TerminalID>
<hyp:LoadValue>10</hyp:LoadValue>
<hyp:CurCode>GBP</hyp:CurCode>
<hyp:Reason></hyp:Reason>
<hyp:ItemSrc>2</hyp:ItemSrc>
<hyp:SysDate></hyp:SysDate>
<hyp:LoadFundsType></hyp:LoadFundsType>
<hyp:LoadSrc>2</hyp:LoadSrc>
<hyp:LoadFee>0</hyp:LoadFee>
<hyp:LoadedBy></hyp:LoadedBy>
<hyp:CreateImage>1</hyp:CreateImage>
<hyp:CreateType>1</hyp:CreateType>
<hyp:CustAccount></hyp:CustAccount>
<hyp:ActivateNow>1</hyp:ActivateNow>
<hyp:SourceDesc></hyp:SourceDesc>
<hyp:StartDate></hyp:StartDate>
<hyp:ExpDate></hyp:ExpDate>
<hyp:CVV></hyp:CVV>
<hyp:CardName></hyp:CardName>
<hyp:MaskedPAN></hyp:MaskedPAN>
<hyp:LimitsGroup>PMT-VL-002</hyp:LimitsGroup>
<hyp:MCCGroup></hyp:MCCGroup>
<hyp:PERMSGroup>PMT-CU-002</hyp:PERMSGroup>
<hyp:FeeGroup></hyp:FeeGroup>
<hyp:ScheduledFeeGroup></hyp:ScheduledFeeGroup>
<hyp:WSFeeGroup></hyp:WSFeeGroup>
<hyp:ProductRef></hyp:ProductRef>
<hyp:CarrierType></hyp:CarrierType>
<hyp:Fulfil1></hyp:Fulfil1>
<hyp:Fulfil2></hyp:Fulfil2>
<hyp:DelvMeth></hyp:DelvMeth>
<hyp:ThermalLine1></hyp:ThermalLine1>
<hyp:ThermalLine2></hyp:ThermalLine2>
<hyp:Lang></hyp:Lang>
<hyp:EmbossLine4></hyp:EmbossLine4>
<hyp:ImageID></hyp:ImageID>
<hyp:LogoFrontID></hyp:LogoFrontID>
<hyp:LogoBackID></hyp:LogoBackID>
<hyp:Replacement></hyp:Replacement>
<hyp:PrimaryToken></hyp:PrimaryToken>
<hyp:DelvAddrL1></hyp:DelvAddrL1>
<hyp:DelvAddrL2></hyp:DelvAddrL2>
<hyp:DelvAddrL3></hyp:DelvAddrL3>
<hyp:DelvCity></hyp:DelvCity>
<hyp:DelvPostcode></hyp:DelvPostcode>
<hyp:DelvCounty></hyp:DelvCounty>
<hyp:DelvCountry></hyp:DelvCountry>
<hyp:DelvCode></hyp:DelvCode>
<hyp:SMSRequired>1</hyp:SMSRequired>
<hyp:IsLive>1</hyp:IsLive>
<hyp:CardManufacturer></hyp:CardManufacturer>
<hyp:CoBrand></hyp:CoBrand>
<hyp:ExternalAuth></hyp:ExternalAuth>
<hyp:LinkageGroup></hyp:LinkageGroup>
<hyp:VanityName></hyp:VanityName>
<hyp:PBlock></hyp:PBlock>
<hyp:PINMailer></hyp:PINMailer>
<hyp:FXGroup></hyp:FXGroup>
<hyp:Email>joe.bloggs@gmail.com</hyp:Email>
<hyp:MailOrSMS>0</hyp:MailOrSMS>
<hyp:Quantity></hyp:Quantity>
<hyp:AuthCalendarGroup></hyp:AuthCalendarGroup>
<hyp:LoadToken></hyp:LoadToken>
<hyp:RequiredBankingFeatures>
<hyp:ExistingToken></hyp:ExistingToken>
<hyp:BankingInEnabled>TRUE</hyp:BankingInEnabled>
<hyp:BankingOutEnabled>TRUE</hyp:BankingOutEnabled>
<hyp:DirectDebitInEnabled>FALSE</hyp:DirectDebitInEnabled>
<hyp:DirectDebitOutEnabled>FALSE</hyp:DirectDebitOutEnabled>
<hyp:CardEnabled>TRUE</hyp:CardEnabled>
<hyp:Status>O</hyp:Status>
<hyp:CompanyName></hyp:CompanyName>
<hyp:AccountName>Joe Bloggs</hyp:AccountName>
</hyp:RequiredBankingFeatures>
<hyp:IsActive>false</hyp:IsActive>
<hyp:CustomerID>C123456</hyp:CustomerID>
<hyp:PaymentTokenUsageGroup>?</hyp:PaymentTokenUsageGroup>
</hyp:request>
</hyp:Ws_CreateCard_V2>
Notes
-
The request has the same fields as are used to create a normal (non-Agency Banking) card. For details of mandatory fields, refer to the Web Services Guide.
-
There are some additional mandatory fields to support Agency Banking:
-
<RequiredBankingFeatures>— the required banking features that are required:-
Populating the
<ExistingToken>field will add banking features onto an existing card. -
Currently supported Agency Banking options include:
BankingInEnabled,BankingOutEnabledandCardEnabled(Note:
DirectDebitOutEnabledwill be available shortly)You can set these Boolean options to true or false; if not populated, this will default to true.
-
When creating a card, the
Statusis automatically set to status "O" (open)
-
-
<CustomerID>— the ID of the customer that this account is to be associated with.
-
Response
Below is an example of the response returned by Thredd.
<Ws_CreateCard_V2Response xmlns="http://www.globalprocessing.ae/HyperionWeb">
<Ws_CreateCard_V2Result>
<WSID>87576567675</WSID>
<IssCode>PMT</IssCode>
<TxnCode>10</TxnCode>
<PublicToken>123456789</PublicToken>
<ExternalRef/>
<LocDate>2021-01-01</LocDate>
<LocTime>120000</LocTime>
<ItemID></ItemID>
<ClientCode>0</ClientCode>
<SysDate></SysDate>
<ActionCode>000</ActionCode>
<LoadValue></LoadValue>
<IsLive>false</IsLive>
<SortCode>11-01-11</SortCode>
<AccountNumber>0123456</AccountNumber>
<AccountName>Mr Joe Bloggs</AccountName>
<ErrorText></ErrorText>
</Ws_CreateCard_V2Result>
</Ws_CreateCard_V2Response>
Notes
-
A successful response returns an
<ActionCode>of 000. -
The response provides details of the linked Agency Banking account:
-
<SortCode>— the sort code from the associated product that was supplied in the request is returned in the response. -
<AccountNumber>— a unique customer account number is returned in the response. -
<AccountName>— the account holder name is returned in the response
-
-
If there is an error, the
<ActionCode>and<ErrorText>field can provide further details.
3.3 Step 3: Registering a Customer for Banking Notifications
API: Ws_Banking_RegisterNotification
Once you have created a card with banking features, you need to make additional calls to enable payment notifications for payments processed on and off the card. There are a number of options, but as a minimum, you should enable both PAYIN and PAYOUT notifications (using two separate calls). For details of the web service fields, see the Web Services Guide.
ALL notifications work at a CUSTOMER level, so if a customer has more than one account, the notification will apply to all of the customer's accounts.
See the example code snippets below:
Request
The request below creates a payment notification for an account statement, which will be run on Friday PM and be sent to the customer’s email address.
<Ws_Banking_RegisterNotification xmlns="http://www.globalprocessing.ae/HyperionWeb">
<request>
<WSID>2021123456789</WSID>
<IssCode>PMT</IssCode>
<CardDesign>int</CardDesign>
<CustomerID> C123456</CustomerID>
<channel>EMAIL</channel>
<daysToRun>
<string>FRIDAY</string>
</daysToRun>
<threshold></threshold>
<timesToRun>
<string>PM</string>
</timesToRun>
<destinations>
<string>joe.bloggs@gmail.com</string>
</destinations>
<type>ACCOUNT_STATEMENT</type>
<status>ACTIVE</status>
</request>
</Ws_Banking_RegisterNotification>
Notes
-
Your request must include
<CustomerID>, the ID of the customer that this account is to be associated with. -
Specify the
<type>of notification to enable. Currently supported options are: PAYOUT and PAYIN. See Notification Type. -
<channel>is dependent on<type>:-
If
<type>is PAYOUT or PAYIN, then set the channel to WEBHOOK. -
The EMAIL channel option is currently not available to Thredd customers.
-
-
You can use the
<daysToRun>field to set the days on which to run the notification. -
You can use the
<timesToRun>field to set the time at which to run the notification: AM (morning) or PM (afternoon). -
You can set the status of the notification to ACTIVE or INACTIVE.
-
You need to create separate calls for each type of notification you want to set up for the customer.
Response
Below is an example of the response returned by Thredd.
<Ws_Banking_RegisterNotificationResponse xmlns="http://www.globalprocessing.ae/HyperionWeb">
<Ws_Banking_RegisterNotificationResult>
<WSID>2021123456789</WSID>
<IssCode>PMT</IssCode>
<ActionCode>000</ActionCode>
<Messages>
<BankingError>
<field> </field>
<code> </code>
<message> </message>
<error> </error>
</BankingError>
</Messages>
</Ws_Banking_RegisterNotificationResult>
</Ws_Banking_RegisterNotificationResponse>
Notes
-
A successful response returns an
<ActionCode>of 000.
-
If there is an error, the
<ActionCode>and<Messages>section can provide further details.
Notification Type
Refer to the table below for details of supported notification types.
|
Type |
Description |
|---|---|
|
PAYOUT |
Notification sent to the web hook set up for your program whenever there is a payment out of the account. |
|
PAYIN |
Notification sent to the web hook set up for your program whenever there is a payment into the account. |
|
DDINCOMINGDEBIT |
Notification sent to the web hook set up for your program whenever there is a Direct Debit payment out of the account. |
|
DDMANDATE |
Notification sent to the web hook set up for your program whenever there is a Direct Debit mandate created. |
3.4 Making External Payments
API: Ws_Banking_TransferFunds
This web service makes an external payment via the faster payment banking system where a card has been set up for Agency banking, with an associated bank account.
The Faster Payments notification is processed immediately; actual funds are transferred once the recipient bank has acknowledged and accepted the payment; the entire process typically takes seconds.
For details of the web service fields, see the Web Services Guide.
See the example code snippet below:
Request
<hyp:Ws_Banking_TransferFunds>
<hyp:request>
<hyp:WSID>76565675</hyp:WSID>
<hyp:IssCode>PMT</hyp:IssCode>
<hyp:PublicToken>123456789</hyp:PublicToken>
<hyp:Beneficiary>
<hyp:AccountNumber>98765432</hyp:AccountNumber>
<hyp:SortCode>333333</hyp:SortCode>
<hyp:AccountName>S Wilson</hyp:AccountName>
</hyp:Beneficiary>
<SEPABeneficiaryAddress>
<AddressLine1>42 The Street</AddressLine1>
<AddressLine2>The Town</AddressLine2>
<PostTown>London </PostTown>
<PostCode>ABC 1234</PostCode>
<Country>UK</Country>
</SEPABeneficiaryAddress>
<hyp:Reference>test load</hyp:Reference>
<hyp:AmountOfPayment>7.00</hyp:AmountOfPayment>
<hyp:AuthorisedBy>S Wilson</hyp:AuthorisedBy>
<hyp:Currency>GBP</hyp:Currency>
<hyp:PaymentMethod>FasterPaymentOut</hyp:PaymentMethod>
<hyp:Direction>Outbound</hyp:Direction> </hyp:request>
</hyp:Ws_Banking_TransferFunds>
Notes
-
In the
<PublicToken>field, you must specify the 9-digit public token associated with the account (this token is always returned in the response to a card create request,Ws_CreateCard_V2). -
<Beneciary>fields are mandatory and must contain details of the account where the money is going to. -
<SEPABeneficiaryAddress>— the address of the payment beneficiary is optional. -
<PaymentMethod>is mandatory and specifies how the payment is being made. You should set this to FasterPaymentOut. -
You must specify a payment amount using the
<AmountOfPayment>field. -
<Direction>indicates the direction of the payment. This must be set to Outbound.
Response
<Ws_Banking_TransferFundsResponse xmlns="http://www.globalprocessing.ae/HyperionWeb">
<Ws_Banking_TransferFundsResult>
<WSID>76565675</WSID>
<Response>Success</Response>
<TransactionID>60199453</TransactionID>
<ErrorText></ErrorText>
<ActionCode>000</ActionCode>
<RecipientActionCode>000</ RecipientActionCode >
<RecipientTranactionID>6446546565654</RecipientTranactionID>
<BankTranactionID>5478934</BankTranactionID>
</Ws_Banking_TransferFundsResult>
</Ws_Banking_TransferFundsResponse>
Notes
-
The account is first checked to ensure that banking out is enabled.
-
The account is then checked against the Issuer-defined Deny list, as set up in the Thredd system via Smart Client; see Blocking Bank Accounts. This makes two checks: the source account is not on the Deny list; the destination account is not on the Deny List.
-
The final checks are the standard velocity/balance checks.
-
A successful response returns a response status of Success and an
<ActionCode>of 000. -
Thredd returns a
<TransactionID>which can be used to track the transaction on the Thredd system, and a<BankTranactionID>, which can be used to track the transaction on the banking network. -
If there is an error, the
<ActionCode>and<Messages>section can provide further details.
This response only indicates that the request has been successfully received (and not that the payment has been sent or received). The payment request will then be submitted to the banking network. Once a response is received from the recipient bank, Thredd will be notified via webhook and the payment will be visible in Smart Client.
3.5 Retrieving a Direct Debit Mandate
API: Ws_Banking_DD_GetMandate
This web service retrieves all mandates for a given token.
For details of the web service fields, see the Web Services Guide.
See the example code snippets below:
3.5.1 Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hyp="http://globalprocessing.ae/HyperionWeb">
<soapenv:Header>
<hyp:AuthSoapHeader>
<!--Optional:-->
<hyp:strUserName>OnePayTest1</hyp:strUserName>
<!--Optional:-->
<hyp:strPassword>********</hyp:strPassword>
</hyp:AuthSoapHeader>
</soapenv:Header>
<soapenv:Body>
<hyp:WS_Banking_DD_GetMandates>
<hyp:requests>
<!--Optional:-->
<hyp:WSID>${=(long)(Math.random()*Long.MAX_VALUE)}</hyp:WSID>
<!--Optional:-->
<hyp:IssCode>ONE</hyp:IssCode>
<hyp:CardDesign>2018</hyp:CardDesign>
<hyp:Token>106239304</hyp:Token>
</hyp:request>
</hyp:WS_Banking_DD_GetMandates>
</soapenv:Body>
</soapenv:Envelope>
3.5.2 Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<WS_Banking_DD_GetMandatesResponse xmlns="http://globalprocessing.ae/HyperionWeb">
<WS_Banking_DD_GetMandatesResult>
<WSID>3371287256120270848</WSID>
<ActionCode>000</ActionCode>
<DDMandates>
<DDMandate>
<MandateID>M101BZWED</MandateID>
<MerchantName>M101BZWED</MerchantName>
<LastScheduledAmount>5.5550</LastScheduledAmount>
<MandateStatus>EXPIRE</MandateStatus>
<MandateCreatedDate>17/03/2022 10:11:28</MandateCreatedDate>
</DDMandate>
<DDMandate>
<MandateID>M101BZWEF</MandateID>
<MerchantName>M101BZWEF</MerchantName>
<LastScheduledAmount>0.0000</LastScheduledAmount>
<MandateStatus>EXPIRE</MandateStatus>
<MandateCreatedDate>15/03/2022 10:11:28</MandateCreatedDate>
</DDMandate>
</DDMandates>
</WS_Banking_DD_GetMandatesResult>
</WS_Banking_DD_GetMandatesResponse>
</soap:Body>
</soap:Envelope>
3.6 Cancelling a Direct Debit Mandate
API: Ws_Banking_DD_CancelMandate
This web service cancels a specific mandate for a particular direct debit mandate Id <MandateId> and token.
For details of the web service fields, see the Web Services Guide.
See the example code snippets below:
3.6.1 Request
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<AuthSoapHeader xmlns="http://globalprocessing.ae/HyperionWeb">
<strUserName>string</strUserName>
<strPassword>string</strPassword>
</AuthSoapHeader >
</soap:Header>
<soap:Body>
<WS_Banking_DD_CancelMandate xmlns="http://globalprocessing.ae/HyperionWeb">
<request>
<WSID>string<WSID>
<IssCode>string</IssCode>
<CardDesign>string</CardDesign>
<Token>PUBTOKEN/PANPUBT</Token>
<MandateID>string</MandateID>
<MerchantName>string</MerchantName>
<CancellationCode>string</CancellationCode>
</request>
</WS_Banking_DD_CancelMandate>
</soap:Body>
</soap:Envelope>
3.6.2 Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<WS_Banking_DD_CancelMandateResponse xmlns="http://globalprocessing.ae/HyperionWeb">
<WS_Banking_DD_CancelMandateResult>
<WSID>string</WSID>
<ActionCode>string</ActionCode>
<Messages>
<Banking_Error>
<field>string</field>
<code>string</code>
<message>string</message>
<error>string</error>
</Banking_Error>
</Messages>
</WS_Banking_DD_CancelMandateResult>
</WS_Banking_DD_CancelMandateResponse>
</soap:Body>
</soap:Envelope>