Orange Money PSD2
REGISTRATION:
In order to register yourself as an official TPP partner with OMY. You need to send the following details to psd2.orangemoney@orange.com:
- Return Urls in case of changes in SCA approach in the future.
- A way to get the public key (in certificate form) with which you will sign the jwt tokens used for oAuth service.
- Official name with which you want to be registered. Keep in mind that this will be displayed to the user when authorizing your requests.
SUMMARY:
General steps for a successful flow
1. Get authorization token
Get Authorization token from authentication server with the given credentials after registration.
Ensure that the appropriate scope is requested in the authorization token:
- PIS: "payments"
- AIS: "accounts"
Use POST on this endpoint: https://www.orange.ro/accounts/token. Here is an example call to requesting a authorization token
The client assertion (YourClientAssertionJWT) used in the below call can be created according to openBanking specifications described here: Open Banking Security
curl --location --request POST 'https://www.orange.ro/accounts/token' \
--header 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion=YourClientAssertionJWT ' \
--data-urlencode 'audience=OpenBankingRSAud' \
--data-urlencode 'scope=payments'
2. Initiate
Use the above appropriate scope token to initiate an account information consent(AIS) or a payment request(PIS):
3. Approve requests
The way to approve an AIS (AIS) or a PIS(PIS) request, is for the user to login to open their OMY app where they will find the requests waiting for their approval. The request has a validity of 5 minutes before it expires!
4. Status Of Request
Use the "/status" endpoints for both AIS and PIS to see the status of your request. The statuses available are the one described in the PSD2 Specification.
5. Account Information Access
In case of AIS requests these are the resource endpoints available to a tpp once the user has approved the initial consent request.
Approve Requests:
Below a couple of examples on how the screens appear for the user and how he can approve your requests:
Main Overview Screen

Pending Requests Overview Screen

Account Access Request Screen

Transaction Request Screen

AIS:
Account Information Consent Request
BasePath:
“/mfs-psd2-pis”
Endpoint:
POST /v2/consents
Creates an account information consent resource at the ASPSP regarding access to account specified in this request.
Query Parameters:
No request body
Request Header:
Attribute | Type | Condition | Description |
---|---|---|---|
x-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Authorization | String | Mandatory | OAuth token. |
TPP-Redirect-URI | String | Mandatory | URI of the TPP, where the transaction flow shall be redirected to after a Redirect. |
Request Body:
Attribute | Type | Condition | Description |
---|---|---|---|
access | Account Access | Mandatory | Definition of the entity at Section Account Access |
msisdn | String | Optional | Customer msisdn |
recurringIndicator | Boolean | Mandatory | true, if the consent is for recurring access to the account data false, if the consent is for one access to the account data |
validUntil | ISODate | Mandatory | This parameter is requesting a valid until date for the requested consent. The content is the local ASPSP date in ISODate Format, e.g. 2017-10-30. If a maximal available date is requested, a date in far future is to be used: "9999-12-31". The consent object to be retrieved by the GET Consent Request will contain the adjusted date. |
frequencyPerDay | Integer | Mandatory | This field indicates the requested maximum frequency |
Response Codes:
201 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Response Header:
Attribute | Type | Condition | Description |
---|---|---|---|
Location | String | Mandatory | Location of the created resource |
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
ASPSP-SCA-Approach | UUID | Mandatory | DECOUPLED |
Response Body:
Attribute | Type | Condition |
---|---|---|
consentStatus | Consent Status | Mandatory |
consentID | String | Mandatory |
balances | Balances | Optional |
Consent Staus
BasePath:
“/mfs-psd2-pis”
Endpoint:
GET /v2/consents/{consentId}/status
Gets the consent status for AIS.
Query Parameters:
No request body
Path Variables:
Attribute | Type | Description |
---|---|---|
consentId | String | Consent id received on initiation. |
Request Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Authorization | String | Mandatory | OAuth token. |
Response Codes:
200 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Response Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Response Body:
Attribute | Type | Condition |
---|---|---|
consentStatus | Consent Status | Mandatory |
consentID | String | Mandatory |
1. Read Account List
BasePath:
“/mfs-psd2-pis”
Endpoint:
GET /v2/accounts { query-parameters }
Reads a list of bank accounts, with balances where required. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed list of accounts depends then on the PSU ID and the stored consent addressed by consentId, respectively the OAuth2 access token.
Query Parameters:
Attribute | Type | Condition | Description |
---|---|---|---|
withBalance | Boolean | Optional | If contained, this function reads the list of accessible payment accounts including the booking balance, if granted by the PSU in the related consent and available by the ASPSP. This parameter might be ignored by the ASPSP. |
Request Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | String | Mandatory | Shall be contained since "Establish Consent Transaction" was performed via this API before. |
Authorization | String | Mandatory | An OAuth2 based authentication was performed in a pre-step. |
Request Body:
No request body
Response Codes:
200 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
Response Header:
Attribute | Type | Condition | Description |
---|---|---|---|
x-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Response Body:
Attribute | Type | Condition |
---|---|---|
accounts | Array: Account Details | Mandatory |
Example:
Response body (example 1)
Response in case of an example, where the consent has been given for one IBAN and balances
{
"accounts": [
{
"resourceId": "1001",
"iban": "RO66ORMF1715363001ORANGE",
"currency": "EUR",
"product": "Moneda scripturala",
"status": "enabled",
"balances": [
{
"balanceType": "closingBooked",
"balanceAmount": {
"currency": "EUR",
"amount": "500"
}
},
{
"balanceType": "expected",
"balanceAmount": {
"currency": "EUR",
"amount": "342"
}
}
]}
]}
Response body (example 2)
Response in case of an example, where the consent has been given for two different IBANs and balances
{
{
"accounts": [
{
"resourceId": "1001",
"iban": "RO66ORMF1715363001ORANGE",
"currency": "EUR",
"product": "Moneda scripturala",
"status": "enabled",
"balances": [
{
"balanceType": "closingBooked",
"balanceAmount": {
"currency": "EUR",
"amount": "500"
}
},
{
"balanceType": "expected",
"balanceAmount": {
"currency": "EUR",
"amount": "342"
}
}
]
},
{
"resourceId": "1002",
"iban": "RO66ORMF1715363002ORANGE",
"currency": "EUR",
"product": "Moneda scripturala",
"status": "enabled",
"balances": [
{
"balanceType": "closingBooked",
"balanceAmount": {
"currency": "EUR",
"amount": "123"
}
},
{
"balanceType": "expected",
"balanceAmount": {
"currency": "EUR",
"amount": "210"
}
}
]
}
]
}
2. Read Account Details
Endpoint:
GET /v2/accounts/{ account-id } { query-parameters }
Reads details about an account, with balances where required. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed details of this account depends then on the stored consent addressed by consentId, respectively the OAuth2 access token.
Query Parameters:
Attribute | Type | Condition | Description |
---|---|---|---|
withBalance | Boolean | Optional | If contained, this function reads the details of the addressed account including the booking balance, if granted by the PSU's consent and if supported by ASPSP. This data element might be ignored by the ASPSP. |
Request Header:
Attribute | Type | Condition | Description |
---|---|---|---|
x-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | String | Mandatory | Shall be contained since "Establish Consent Transaction" was performed via this API before. |
Authorization | String | Mandatory | An OAuth2 based authentication was performed in a pre-step. |
Request Body:
No request body
Response Codes:
200 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Response Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Response Body:
Attribute | Type | Condition |
---|---|---|
accounts | Account Details | Mandatory |
Example:
../v2/accounts/1001?withBalance=true
{
{
"resourceId": "1001",
"iban": "RO66ORMF1715363001ORANGE",
"currency": "EUR",
"product": "Moneda scripturala",
"status": "enabled",
"balances": [
{
"balanceType": "closingBooked",
"balanceAmount": {
"currency": "EUR",
"amount": "500"
}
},
{
"balanceType": "expected",
"balanceAmount": {
"currency": "EUR",
"amount": "342"
}
}
]
}
3. Read Balance
Endpoint:
GET /v2/accounts/ { account-id } /balances
Reads account data from a given account addressed by "account-id".
Path Parameters:
Attribute | Type | Description |
---|---|---|
account-id | String | This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. |
Request Body:
No request body
Response Codes:
200 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Request Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | String | Mandatory | Shall be contained since "Establish Consent Transaction" was performed via this API before. |
Authorization | String | Mandatory | An OAuth2 based authentication was performed in a pre-step. |
Request Body:
No request body
Response Codes:
200 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Response Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Response Body:
Attribute | Type | Condition |
---|---|---|
accounts | iban | Mandatory |
balances | Array: Balance | Mandatory |
Example:
../v2/accounts/1001/balances
{
{
"account": "RO66ORMF1715363001ORANGE",b
"balances": [
{
"balanceType": "closingBooked",
"balanceAmount": {
"currency": "EUR",
"amount": "500"
}
},
{
"balanceType": "expected",
"balanceAmount": {
"currency": "EUR",
"amount": "342"
}
}
]
}
4. Read Transactions
Endpoint:
GET /v2/accounts/ { account-id } /transactions {query-parameters}
Path Parameters:
Attribute | Type | Description |
---|---|---|
account-id | String | This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. |
Query Parameters:
Attribute | Type | Condition | Description |
---|---|---|---|
pageNumber | Integer | Mandatory | Page requested. It's index is 0 based. |
pageSize | Integer | Mandatory | Number of transactions per page. LIMITED to 100 requests per page! |
dateFrom | ISODate | Conditional | Starting date (inclusive the date dateFrom) of the transaction list. |
dateTo | ISODate | Mandatory | End date (inclusive the data dateTo) of the transaction list, default is "now" if not given. |
bookingStatus | String | Mandatory | Permitted codes are "booked", "pending" and "both" "booked" shall be supported by the ASPSP. To support the "pending" and "both" feature is optional for the ASPSP. |
Request Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Consent-ID | String | Mandatory | Shall be contained since "Establish Consent Transaction" was performed via this API before. |
Request Body:
No request body
Response Codes:
201 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Response Header:
Attribute | Type | Condition | Description |
---|---|---|---|
Content-Type | String | Mandatory | application/json |
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Response Body:
Attribute | Type | Condition |
---|---|---|
account | Account Reference (iban) | Mandatory |
transactions | Account Report | Optional |
pagination | Pagination | Optional |
Example:
Request:
… v2/accounts/1001/transactions?dateFrom=2018-01-01&dateTo=2018-07-29&bookingStatus=both&pageNumber=1&pageSize=2
Response:
{
"account": {
"iban": "RO66ORMF1715363001ORANGE"
},
"transactions": {
"booked": [
{
"bookingDate": "2018-03-02",
"direction": "CREDIT",
"transactionAmount": {
"currency": "EUR",
"amount": "432.00"
},
"creditorName": "ENTITY 1",
"debtorName": "ENTITY 2",
"remittanceInformationUnstructured": {
"title": "Tranzactie Orange Money",
"description": "alimentare cu cardul"
}
}
],
"pending": [
{
"bookingDate": "2018-07-02",
"direction": "CREDIT",
"transactionAmount": {
"currency": "EUR",
"amount": "412.00"
},
"creditorName": "ENTITY 7",
"debtorName": "ENTITY 8",
"remittanceInformationUnstructured": {
"title": "Tranzactie Orange Money",
"description": "alimentare cu cardul"
}
}
]
},
"pagination": {
"pageSize": 2,
"hasPrev": true,
"currentPage": 1,
"hasNext": true,
"totalPages": 10,
"totalElements": 19,
"_links": {
"firstPage": {
"href": "v2/accounts/1001/transactions?pageNumber=0&dateFrom=2020-01-08&dateTo=2021-10-08&withBalance=true&bookingStatus=both&pageSize=10"
},
"nextPage": {
"href": "v2/accounts/1001/transactions?pageNumber=2&dateFrom=2020-01-08&dateTo=2021-10-08&withBalance=true&bookingStatus=both&pageSize=10"
},
"lastPage": {
"href": "v2/accounts/1001/transactions?pageNumber=9&dateFrom=2020-01-08&dateTo=2021-10-08&withBalance=true&bookingStatus=both&pageSize=10"
}
}
}
}
6. Confirmation of Funds Request
Endpoint:
POST /v2/funds-confirmations
Creates a confirmation of funds request at the ASPSP.
Query Parameters:
No specific query parameter.
Request Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
Authorization | String | Mandatory | OAuth token. |
TPP-Redirect-URI | String | Mandatory | URI of the TPP, where the transaction flow shall be redirected to after a Redirect. |
Request Body:
Attribute | Type | Condition | Description |
---|---|---|---|
cardNumber | String | Optional | Card Number of the card issued by the PIISP. Should be delivered if available. |
account | iban | Mandatory | The merchant where the card is accepted as an information to the PSU. |
payee | String | Optional | An OAuth2 based authentication was performed in a pre-step. |
instructedAmount | Amount | Mandatory | Transaction amount to be checked within the funds check mechanism. |
Response Codes:
201 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Response Header:
Attribute | Type | Condition | Description |
---|---|---|---|
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
fundsAvailable | String | Mandatory | Equals true if sufficient funds are available at the time of the request, false otherwise. |
- The additional card number might support the choice of the sub-account.
- If no card number, but the PSU account identifier is contained: check on default account registered by customer.
- If no card number but the PSU and the account identifier with currency is contained: check the availability of funds on the corresponding sub-account.
- If card number and the PSU account identifier is contained:: check on sub-account addressed by card, if the addressed card is registered with one of the sub-accounts.
- If the card number is not registered for any of the accounts, the card number is ignored.
Account Details:
Attribute | Type | Description |
---|---|---|
resourceID | String | This is the data element to be used in the path when retrieving data from a dedicated account |
iban | String | |
currency | String | |
product | String | |
status | String | Account status. The value is one of the following:
|
balances | Array: Balances |
Balances
Attribute | Type |
---|---|
balanceAmount | Amount |
balanceType | String |
referenceDate | ISODate |
Account Report
Attribute | Type |
---|---|
booked | Array: Transaction |
pending | Array: Transaction |
Transactions
Attribute | Type | Description |
---|---|---|
bookingDate | ISODate | The Date when an entry is posted to an account on the ASPSPs books. |
transactionAmount | Amount | The amount of the transaction as billed to the account. |
creditorName | String | Name of the creditor if a "Debited" transaction |
debtorName | String | Name of the debtor if a "Credited" transaction. |
PIS:
Payment Initiation Endpoint:
Summary
There are 2 types of transactions that can take place:
SEPARON
types of transaction are simple and require no prerequisites. They only need to have the basic mandatory fields described in the body.FOREGIN_CURRENCY
types of transaction are more complex and require one prerequisite. ThecreditorId
needs to be present.
The type of transaction needs to be present in the body of the initiation request.
BasePath:
“/mfs-psd2-pis”
Request:
POST BasePath + "/v2/payments/sepa-credit-transfers"
Headers:
Attribute | Type | Condition | Description |
---|---|---|---|
Content-Type | application/json | Mandatory | |
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party |
Authorization | String | Mandatory | Bearer Token received on OAuth2 based authentication performed in a pre-step |
Request Body:
Payment initation body
Attribute | Type | Condition | Description |
---|---|---|---|
transactionType | String | Mandatory | SEPARON / FOREIGN_CURRENCY (One of these 2 vaues) |
debtorAccount | Account Reference | Optional | Definition of the entity at Section 10 Account Reference |
instructedAmount | Amount | Mandatory | Definition of the entity at Section 10 Amount |
creditorAccount | Account Reference | Mandatory | Definition of the entity at Section 10 Account Reference |
creditorName | String | Mandatory | Maximum 70 characters |
creditorAgent | String | Optional | Maximum 70 characters |
creditorName | String | Optional | Maximum 70 characters |
creditorId | String | Optional depending on transaction type | This will be the beneficiary id that you defined beforehand. It's Mandatory when performing a FOREIGN_CURRENCY transaction, otherwise you will receive a validation error |
creditorAddress | Address | Optional | Definition of the entity at Section 10 Address |
remittance | Remittance | Mandatory | Maximum 140 characters |
Response Codes:
201 OK - Successful Response Code
400 BAD REQUEST - Error Response Code | duplicate x-Request-ID, malformed IBAN, currency other than RON, other validation errors
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
502 BAD GATEWAY - Error Response Code | failure from other services in the OMY ecosystems
Response Headers:
Location | String | Condition | Description |
---|---|---|---|
Location | String | Mandatory | Location of the created resource, if created |
X-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party |
ASPSP-SCA-Approach | String | Mandatory | The OAuth SCA approach will be subsumed by REDIRECT |
Response Body:
Attribute | Type | Condition | Description |
---|---|---|---|
transactionStatus | Transaction Status | Mandatory | |
paymentID | String | Mandatory | Resource identification of the generated payment initiation resource |
transactionFees | Amount | Optional | Can be used by the ASPSP to transport transaction |
transactionFeeIndicator | Boolean | Optional | If equals true, the transaction will involve specific transaction cost as shown by the ASPSP |
scaMethods | Array of authentication objects | Conditional | Is not applicable at the current moment as only one authentication method will be used |
_links | Links | Mandatory | A list of hyperbolinks to be recognized by the TPP. The actual hyperlinks used in the response depend on the dynamical decisions of the ASPS when processing the request |
psuMessage | String | Optional | Max 512 characters, text to be displayed to the PSU |
tppMessages | Array of TPP Message Information | Optional | Messages to the TPP on operational issues |
Initiate a SEPARON transaction:
SEPARON transactions are transactions that are done in Romanian currency, RON.
As decribed above this type of transaction requires no prerequisites, just add the correct transactionType
field and set it to SEPARON.
Just make sure the instructedAmount
object has the correct currency in it, to match the type. For RON use SEPARON, otherwise you will receive a validation error with the appropriate error message.
Here is an example of an appropriate SEPARON payload
{
"transactionType":"SEPARON",
"debtorAccount":{
"bban":"1002a",
"pan":"1003a",
"maskedPan":"3006a",
"msisdn":"075xxxxxxx",
"currency":"RON"
},
"instructedAmount":{
"currency":"RON",
"amount":"2.5"
},
"creditorAccount":{
"iban":"RO36BTRLRONCRT0227XXXXXX",
"bban":"6789",
"pan":"9753",
"maskedPan":"3579",
"currency":"RON"
},
"creditorAgent":"Myself",
"creditorName":"The name of the creditor that will receive the money",
"creditorAddress":{
"street":"someStreet",
"building number":"44",
"city":"someCity",
"postalCode":"2211xx",
"country":"RO"
},
"remittance":{
"reference":"TPP reference",
"referenceType":"TPP reference type",
"referenceIssuer":"TPP issuer"
}
}
Initiate a FOREIGN_CURRENCY transaction:
FOREIGN_CURRENCY transactions are transactions that are done in ANY other currency but RON
As decribed above this type of transaction requires one prerequisite. The creditorId
needs to be added to the payload, along with the used currency.
You can see how to create one in the BENEFICIARY section
For now let's assume you've defined a beneficiary and have gotten the corresponding details. You will use the id of the beneficiary created to supply the creditorId
field, as in the below example.
As you can see below the currency of the debtorAccount
stays the same because it's still in RON. However, the rest of the currency has changed to match the defined beneficiary.
{
"transactionType": "FOREIGN_CURRENCY",
"debtorAccount": {
"bban": "1002a",
"pan": "1003a",
"maskedPan": "3006a",
"msisdn": "075xxxxxxx",
"currency": "RON"
},
"instructedAmount": {
"currency" : "EUR",
"amount": "2.5"
},
"creditorAccount": {
"iban": "GB01TCCL5XXXXXXXXXXXX",
"bban": "6789",
"pan": "9753",
"maskedPan": "3579",
"currency": "EUR"
},
"creditorId": "1ae2cdfe-e4c0-46c9-92c0-180037b2156f",
"creditorAgent": "Myself",
"creditorName": "The name of the creditor that will receive the money",
"creditorAddress": {
"street": "someStreet",
"building number" : "44",
"city": "someCity",
"postalCode": "2211xx",
"country":"RO"
},
"remittance": {
"reference": "TPP reference",
"referenceType": "TPP reference type",
"referenceIssuer": "TPP issuer"
}
}
Payment Status
BasePath:
“/mfs-psd2-pis”
Request:
Get BasePath + “/v2/payments/sepa-credit-transfers/{paymentId}/status"
Path Variables:
Attribute | Type | Description |
---|---|---|
payment ID | String | Resource identification of the related payment |
Request Headers:
Attribute | Type | Condition | Description |
---|---|---|---|
Authorization | String | Mandatory |
Response Codes:
200 OK - Successful Response Code
400 BAD_REQUEST - Error Response Code | Specific message regarding what is wrong with the request
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
Response Body:
Attribute | Type | Condition | Description |
---|---|---|---|
transactionStatus | String | Mandatory | 10 Links |
Beneficiary
Summary
Beneficiaries are required for FOREIGN_CURRENCY transactions.
Beneficiaries defined by TPP will not be visible tot he user! The TPP is responsible for managing the beneficiary details in their own system once created. They will not be visible in the PSD2 API, there is no GET option for them!
Once defined, the identifier of the beneficiary can be used in the filed creditorId
in the payload of the Initiation request.
Get Beneficiary Requirements:
BasePath:
“/mfs-psd2-pis”
Request:
GET BasePath + “/v2/beneficiary/requirements"
Query Params:
Attribute | Type | Description |
---|---|---|
beneficiaryType | String | individual / company |
currency | String | EUR / USD / GBP etc... |
bankAccountCountry | String | Two-letter country code. |
beneficiaryCountry | String | Two-letter country code. If the beneficiary is a company, the country in which the company is registered. If the beneficiary is an individual, a country in which the beneficiary holds nationality. |
Request Headers:
Attribute | Type | Condition | Description |
---|---|---|---|
Authorization | String | Mandatory | Received oAuth token received initially with the appropriate payments scope. |
Response Codes:
200 OK - Successful Response Code
400 BAD_REQUEST - Error Response Code | Specific message regarding what is wrong with the request
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
Response Body(all objects inside the response are optional and they are all listed to show what you might expect):
{
"details": [
{
"payment_type": "priority",
"beneficiary_entity_type": "individual",
"beneficiary_address": "^.{1,255}",
"beneficiary_city": "^.{1,255}",
"beneficiary_country": "^[A-z]{2}$",
"beneficiary_first_name": "^.{1,255}",
"beneficiary_last_name": "^.{1,255}",
"acct_number": "^\\d{8}$",
"sort_code": "^\\d{6}$"
},
{
"payment_type": "priority",
"beneficiary_entity_type": "company",
"beneficiary_address": "^.{1,255}",
"beneficiary_city": "^.{1,255}",
"beneficiary_country": "^[A-z]{2}$",
"beneficiary_company_name": "^.{1,255}",
"acct_number": "^\\d{8}$",
"sort_code": "^\\d{6}$"
},
{
"payment_type": "priority",
"beneficiary_entity_type": "individual",
"beneficiary_address": "^.{1,255}",
"beneficiary_city": "^.{1,255}",
"beneficiary_country": "^[A-z]{2}$",
"beneficiary_first_name": "^.{1,255}",
"beneficiary_last_name": "^.{1,255}",
"iban": "([A-Z0-9]\\s*){15,34}",
"bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
},
{
"payment_type": "priority",
"beneficiary_entity_type": "company",
"beneficiary_address": "^.{1,255}",
"beneficiary_city": "^.{1,255}",
"beneficiary_country": "^[A-z]{2}$",
"beneficiary_company_name": "^.{1,255}",
"iban": "([A-Z0-9]\\s*){15,34}",
"bic_swift": "^[0-9A-Z]{8}$|^[0-9A-Z]{11}$"
},
{
"payment_type": "regular",
"acct_number": "^\\d{8}$",
"sort_code": "^\\d{6}$",
"beneficiary_entity_type": "individual"
},
{
"payment_type": "regular",
"acct_number": "^\\d{8}$",
"sort_code": "^\\d{6}$",
"beneficiary_entity_type": "company"
}
]
}
Create Beneficiary:
BasePath:
“/mfs-psd2-pis”
Request:
POST BasePath + “/v2/beneficiary"
Request Headers:
Attribute | Type | Condition | Description |
---|---|---|---|
Authorization | String | Mandatory | Received oAuth token received initially with the appropriate payments scope. |
Content-Type | String | Mandatory | application/json |
Request Body:
Create Beneficiary payload
Attribute | Type | Condition | Description |
---|---|---|---|
debtorAccount | Account Reference | Mandatory | Definition of the entity at Section Entity definition |
beneficiary | BeneficiaryEntity | Mandatory | Definition of the entity at Section Entity definition |
Response Codes:
200 OK - Successful Response Code
400 BAD_REQUEST - Error Response Code | Specific message regarding what is wrong with the request
401 UNAUTHORIZED - Error Response Code | OAuth authentication failed
403 FORBIDDEN - Error Response Code | unauthorized user for selected action
500 INTERNAL SERVER ERROR - Error Response Code | unhandled business case or internal error
Response Body:
{
"id": "b551c08c-837a-4753-bf24-72fbd86fd883",
"clientId": "011111715",
"name": "Tpp Defined",
"bankAccountHolderName": "CryptoBank",
"bankCountry": "DE",
"currency": "EUR",
"paymentType": "regular",
"beneficiaryEntityType": "individual",
"beneficiaryCountry": "DE",
"beneficiaryAddress": null,
"beneficiaryCity": null,
"beneficiaryFirstName": null,
"beneficiaryLastName": null,
"beneficiaryCompanyName": null,
"bicSwift": null,
"iban": "GB01TCCL53335625861681",
"beneficiaryStateOrProvince": null,
"beneficiaryPostcode": null,
"accountNumber": null,
"aba": null,
"sortCode": null,
"bsbCode": null,
"bankName": null,
"branchCode": null,
"bankCode": null,
"forSave": false
}
Entities Definition
Account Reference
- String
iban
- CurrencyCode
currency
(Currency codes according to the ISO 4217 standard)
Account Access
This entity is subject to the PSD2 specification. It's fields are optional and are treated as described in the public specification.
- Array of Account Reference
accounts
- Array of Account Reference
balances
- Array of Account Reference
transactions
- String
availableAccounts
- String
availableAccountsWithBalance
- String
allPsd2
TPP Message Information
- String
category
- String
code
- String
path
- String
text
Amount
- CurrencyCode
currency
(Currency codes according to the ISO 4217 standard) - String
amount
Address
- String
street
- String
buildingNumber
- String
city
- String
postalCode
- CountryCode
country
(Currency codes according to the ISO 3166-1 standard)
Beneficiary
- String
name
Mandatory - String
bankAccountHolderName
Mandatory - String
bankCountry
Mandatory: Two-letter country code. - String
currency
Mandatory: Two-letter country code. - String
paymentType
Mandatory: regular/priority. - String
beneficiaryEntityType
Mandatory: individual/company. - String
beneficiaryCountry
Mandatory: Two-letter country code. If the beneficiary is a company, the country in which the company is registered. If the beneficiary is an individual, a country in which the beneficiary holds nationality.. - String
iban
Mandatory: Creditor destination account
Links(all fields are optional)
- HrefType
scaRedirect
- HrefType
scaOAuth/strong>
- HrefType
startAuthorisation
- HrefType
startAuthorisationWithPsuIdentification
- HrefType
updatePsuIdentification
- HrefType
startAuthorisationWithProprietaryData
- HrefType
updateProprietaryData
- HrefType
startAuthorisationWithPsuAuthentication
- HrefType
updatePsuAuthentication
- HrefType
startAuthorisationWithEncryptedPsuAuthentication
- HrefType
updateEncryptedPsuAuthentication
- HrefType
startAuthorisationWithTransactionAuthorisation
- HrefType
selectAuthenticationMethod
- HrefType
authoriseTransaction
- HrefType
self
- HrefType
status
- HrefType
scaStatus
- HrefType
account
- HrefType
balances
- HrefType
transactions
- HrefType
transactionDetails
- HrefType
first
- HrefType
next
- HrefType
previous
- HrefType
last
- HrefType
download
Hreftype
- HrefType
href