Get payment product directory

GET https://{domainname}/client/v1/{customerId}/products/{paymentProductId}/directory

Products

Through this API you can retrieve details of the payment products that are configured for your account.

Request

Certain payment products have directories that the consumer needs to pick from. The most well known example is the list of banks for iDeal that the consumer needs to select their bank from. iDeal is however not the only payment product for which this applies. If you have filtered out the fields in the GET payment products call you can retrieve only the directory entries associated with a single payment product using this call. If you are looking to get all details on all payment products including the entries of possible directories we encourage you to use the GET payment products API call without the fields filter. Usually the performance penalty is bigger when you need to do multiple calls with a small response package than one call with a bigger response package. You are however free to choose the best solution for your use case.

Query parameters

Query parameters for this method

Property	Type	Required	Repeat	Details
countryCode	string	yes	no	read close
close Description ISO 3166-1 alpha-2 country code
currencyCode	string	yes	no	read close
close Description Three-letter ISO currency code representing the currency of the transaction

Request example

SDK: iOS

This scenario you will probably use the most

NSString *clientSessionId = @"<clientSessionId from Create Session>";
NSString *customerId = @"<customerId from Create Session>";
NSString *baseURL = @"<clientApiUrl from Create Session>";
NSString *assetBaseURL = @"<assetUrl from Create Session>";
NSString *appIdentifier = @"<your app name>";

ICSession *session = [ICSession sessionWithClientSessionId:clientSessionId
                                                customerId:customerId
                                                   baseURL:baseURL
                                              assetBaseURL:assetBaseURL
                                             appIdentifier:appIdentifier];

NSString *paymentProductId = @"809";

[session directoryForPaymentProductId:paymentProductId countryCode:@"NL" currencyCode:@"EUR" success:^(ICDirectoryEntries *directoryEntries) {
    NSMutableArray *entries = directoryEntries.directoryEntries;
    // Process directory entries.
} failure:^(NSError *error) {
    DLog(@"Error while retrieving payment product directory: %@", [error localizedDescription]);
}];

Responses

Please find below an overview of the possible responses.

Response 200 - OKDirectory

An array of the directory entries is returned that can be used to populate the GUI element that allows the consumer to make the selection

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
entries	array of object	no	read close
close Description List of entries in the directory
items	object	no	read close
close SDK Object type DirectoryEntry
countryNames	array	no	read close
close Description Country name of the issuer, used to group issuers per country Note: this is only filled if supported by the payment product.
issuerId	string	yes	read close
close Description Unique ID of the issuing bank of the customer
issuerList	string	yes	read close
close Description To be used to sort the issuers. short - These issuers should be presented at the top of the list long - These issuers should be presented after the issuers marked as short Note: this is only filled if supported by the payment product. Currently only iDeal (809) support this. Sorting within the groups should be done alphabetically.
issuerName	string	yes	read close
close Description Name of the issuing bank, as it should be presented to the customer

Response example

SDK: iOS

This scenario you will probably use the most

{
    "entries" : [
        {
            "countryNames" : [
                "Nederland"
            ],
            "issuerId" : "ABNANL2A",
            "issuerList" : "short",
            "issuerName" : "ABN Amro Bank"
        },
        {
            "countryNames" : [
                "Nederland"
            ],
            "issuerId" : "ASNBNL21",
            "issuerList" : "long",
            "issuerName" : "ASN Bank"
        }
    ]
}

Response 400 - Bad requestErrorResponse

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
errorId	string	yes	read close
close Description Unique reference, for debugging purposes, of this error response
errors	array of object	yes	read close
close Description List of one or more errors
items	object	no	read close
close SDK Object type APIError
category	string	no	read close
close Description Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values: CONNECT\_PLATFORM\_ERROR - indicating that a functional error has occurred in the Connect platform. PAYMENT\_PLATFORM\_ERROR - indicating that a functional error has occurred in the Payment platform. IO\_ERROR - indicating that a technical error has occurred within the Connect platform or between Connect and any of the payment platforms or third party systems.
code	string	yes	read close
close Description Error code
httpStatusCode	integer	no	read close
close Description HTTP status code for this error that can be used to determine the type of error
id	string	no	read close
close Description ID of the error. This is a short human-readable message that briefly describes the error.
message	string	no	read close
close Description Human-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
propertyName	string	no	read close
close Description Returned only if the error relates to a value that was missing or incorrect. Contains a location path to the value as a JSonata query. Some common examples: a.b selects the value of property b of root property a, a[1] selects the first element of the array in root property a, a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.
requestId	string	no	read close
close Description ID of the request that can be used for debugging purposes

Response example

SDK: iOS

This scenario you will probably use the most

{
    "errorId" : "15eabcd5-30b3-479b-ae03-67bb351c07e6-00000092",
    "errors" : [
        {
            "code" : "20000000",
            "propertyName" : "bankAccountBban.accountNumber",
            "message" : "PARAMETER_NOT_FOUND_IN_REQUEST"
        }
    ]
}

Response 404 - Not foundErrorResponse

When no directory can be found matching the input criteria a HTTP 404 response is returned

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
errorId	string	yes	read close
close Description Unique reference, for debugging purposes, of this error response
errors	array of object	yes	read close
close Description List of one or more errors
items	object	no	read close
close SDK Object type APIError
category	string	no	read close
close Description Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values: CONNECT\_PLATFORM\_ERROR - indicating that a functional error has occurred in the Connect platform. PAYMENT\_PLATFORM\_ERROR - indicating that a functional error has occurred in the Payment platform. IO\_ERROR - indicating that a technical error has occurred within the Connect platform or between Connect and any of the payment platforms or third party systems.
code	string	yes	read close
close Description Error code
httpStatusCode	integer	no	read close
close Description HTTP status code for this error that can be used to determine the type of error
id	string	no	read close
close Description ID of the error. This is a short human-readable message that briefly describes the error.
message	string	no	read close
close Description Human-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
propertyName	string	no	read close
close Description Returned only if the error relates to a value that was missing or incorrect. Contains a location path to the value as a JSonata query. Some common examples: a.b selects the value of property b of root property a, a[1] selects the first element of the array in root property a, a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.
requestId	string	no	read close
close Description ID of the request that can be used for debugging purposes

Response example

SDK: iOS

This scenario you will probably use the most

{
    "errorId" : "3caa7750-a076-48b2-9402-3cb9eea613a6-00001532",
    "errors" : [
        {
            "code" : "210390",
            "message" : "NO DIRECTORY FOUND"
        }
    ]
}