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

Initiate AIS consent
Initiate PIS consent

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!

Approving Requests

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.

AIS consent status
PIS payment status

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.

Read Account List
Read Account Details
Read Balance
Read Transactions
Confirmation Of Funds

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:

1. Read Account List

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 following rules will apply in interpreting the Confirmation of Funds Request for multicurrency accounts:

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: "enabled": account is available "deleted": account is terminated "blocked": account is blocked e.g. for legal reasons
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. The creditorId 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

Hreftype

HrefType href