LinkCy

Beneficiary

List Beneficiaries

Fetch all your beneficiaries.

SecurityLinkcy-Auth
Request
query Parameters
active
boolean

Show results with only active status or non active status. Both statuses are shown by default.

display
boolean

Show only display or non display beneficiaries. Both statuses are shown by default.

sortAttribute
string
Enum: "NAME" "CREATION_DATE"
endUserId
string <uuid>

The ID of the end-user. If empty, the query will return results for all end-users.

status
string
Enum: "DECLINED" "PENDING_REVIEW" "VALID" "PENDING"
pageSize
integer <int32> <= 100

The size of the page to be returned.

page
integer <int32> >= 0

The page number.

sortDirection
string
Enum: "ASC" "DESC"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

get/api/partner/beneficiaries
Request samples 
Response samples 
application/json
{
  • "content": [
    ],
  • "totalElements": 1,
  • "page": 0,
  • "pageSize": 0
}
Add a new beneficiary
Beneficiaries are the one who will receive funds. When you add a beneficiary, the consumer must use the exact full name. If he adds as a beneficiary one of his own accounts, we must be able to detect it. It will simplify Strong Customer Authentication (SCA) during a transfer.


You must fill one of the beneficiary types. BIC / SWIFT code is only required for IBAN. If you want to simplify transfers later, we suggest you add a SWIFT code for US and UK beneficiaries.


This operation might require SCA.


SecurityLinkcy-Auth 
Request 
header Parameters
Linkcy-SCA-Strategy
string
 Default:  PUSH_NOTIFICATION
The strategy to use when a SCA is required:



More information:


    

  • PUSH_NOTIFICATION: will send a notification if the SCA is required.
    • 

  • JOIN_CODE: will return a join code if SCA is required.
    • 

  • FAIL: will fail if SCA is required.
    • 

  • BY_PASS: Sandbox only - will ignore any SCA if used.




ErrorCode


    

  • 409 Conflict
      

    • SCA_REQUIRED: The operation requires SCA. Can be returned if you try to use BY_PASS while not allowed. Will be returned if strategy is FAIL.
      • 

    • SCA_DEVICE_NOT_SET: The operation requires SCA and strategy allows it, but the user has no sca device set up. You need to enroll one first. 





 Enum: "PUSH_NOTIFICATION" "JOIN_CODE" "FAIL" "BY_PASS"  
Linkcy-SCA-Factor
string
 Default:  BIOMETRY
The factor type required for the operation :



More information:


    

  • BIOMETRY: will require fingerprint or face recognition depending on device.
    • 

  • PIN: will require the endpoint pin. When using this factor, a pin must have been registered through the SDK first. Sca pin and end user password can differ.




ErrorCode


    

  • 400 Bad Request
      

    • SCA_FACTOR_NOT_SET: The user has a sca device set up, but the factor requested is not enrolled yet. You must either enroll it or change the factor.





 Enum: "BIOMETRY" "PIN"  
Linkcy-SCA-Id
string <uuid> 
The id of the completed SCA operation.



ErrorCode


    

  • 404 Not Found
      

    • SCA_INTERACTION_NOT_FOUND: The specified id could not be found.
      • 

    

    • 

  • 409 Conflict
      

    • SCA_INTERACTION_NOT_COMPLETED: The SCA interaction is not completed (pending).
      • 

    • SCA_INTERACTION_DECLINED: The SCA interaction was declined by user or expired. 
      • 

    • SCA_INTERACTION_ALREADY_CONSUMED: The SCA interaction has already been used, you need to create a new one.
      • 

    • SCA_INTERACTION_DOES_NOT_MATCH: The SCA interaction does not match the one you are trying to make. Body or url is different.





 
Request Body schema: application/json
required
endUserId
string <uuid> 
The id of the end-user, can be a consumer or corporate. Mandatory if not authenticated as end-user.


 
type
required
string
Describe if the beneficiary is a person or a company.


 Enum: "PERSON" "COMPANY"  
fullName
string  [ 3 .. 70 ] characters 
 Deprecated 
Use name instead


 
name
string  [ 3 .. 70 ] characters 
Complete name of the person (firstName middleName lastName) or name of the company.


 
friendlyName
string  [ 1 .. 255 ] characters 
Friendly name given to the beneficiary.


 
required
SepaBankingDetails (object) or GbpBankingDetails (object) or UsdBankingDetails (object) (BankingDetails) 
 
display
boolean
Display (or not) the beneficiary to the end-user (unusable by end-user).


 
Responses 
201
Created


202
Waiting SCA


400
Bad Request


401
Unauthorized


403
Forbidden


409
Conflict


post/api/partner/beneficiaries
Request samples 
application/json
{
  • "endUserId": "120e9d1f-8444-4b91-85e8-5b208615a3e5",
  • "type": "PERSON",
  • "fullName": "string",
  • "name": "John Michael Doe",
  • "friendlyName": "string",
  • "bankingDetails": {
    },
  • "display": true
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
Get beneficiary's information
Get all information about a beneficiary using its ID.


SecurityLinkcy-Auth 
Request 
path Parameters
beneficiaryId
required
string <uuid> 
 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


404
Not Found


get/api/partner/beneficiaries/{beneficiaryId}
Request samples 
Response samples 
application/json
{
  • "name": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "PERSON",
  • "status": "DECLINED",
  • "active": true,
  • "endUserId": "120e9d1f-8444-4b91-85e8-5b208615a3e5",
  • "friendlyName": "string",
  • "accountType": "IBAN",
  • "updateDate": "2019-08-24T14:15:22Z",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "display": true,
  • "linkcyLedgerId": "a46808dc-b040-4d05-b916-a3302b04dc12",
  • "accountNumber": "string",
  • "sortCode": "string"
}
Patch a beneficiary
Patch a beneficiary.


This operation might require SCA.


SecurityLinkcy-Auth 
Request 
path Parameters
beneficiaryId
required
string <uuid> 
 
header Parameters
Linkcy-SCA-Strategy
string
 Default:  PUSH_NOTIFICATION
The strategy to use when a SCA is required:



More information:


    

  • PUSH_NOTIFICATION: will send a notification if the SCA is required.
    • 

  • JOIN_CODE: will return a join code if SCA is required.
    • 

  • FAIL: will fail if SCA is required.
    • 

  • BY_PASS: Sandbox only - will ignore any SCA if used.




ErrorCode


    

  • 409 Conflict
      

    • SCA_REQUIRED: The operation requires SCA. Can be returned if you try to use BY_PASS while not allowed. Will be returned if strategy is FAIL.
      • 

    • SCA_DEVICE_NOT_SET: The operation requires SCA and strategy allows it, but the user has no sca device set up. You need to enroll one first. 





 Enum: "PUSH_NOTIFICATION" "JOIN_CODE" "FAIL" "BY_PASS"  
Linkcy-SCA-Factor
string
 Default:  BIOMETRY
The factor type required for the operation :



More information:


    

  • BIOMETRY: will require fingerprint or face recognition depending on device.
    • 

  • PIN: will require the endpoint pin. When using this factor, a pin must have been registered through the SDK first. Sca pin and end user password can differ.




ErrorCode


    

  • 400 Bad Request
      

    • SCA_FACTOR_NOT_SET: The user has a sca device set up, but the factor requested is not enrolled yet. You must either enroll it or change the factor.





 Enum: "BIOMETRY" "PIN"  
Linkcy-SCA-Id
string <uuid> 
The id of the completed SCA operation.



ErrorCode


    

  • 404 Not Found
      

    • SCA_INTERACTION_NOT_FOUND: The specified id could not be found.
      • 

    

    • 

  • 409 Conflict
      

    • SCA_INTERACTION_NOT_COMPLETED: The SCA interaction is not completed (pending).
      • 

    • SCA_INTERACTION_DECLINED: The SCA interaction was declined by user or expired. 
      • 

    • SCA_INTERACTION_ALREADY_CONSUMED: The SCA interaction has already been used, you need to create a new one.
      • 

    • SCA_INTERACTION_DOES_NOT_MATCH: The SCA interaction does not match the one you are trying to make. Body or url is different.





 
Request Body schema: application/json
required
active
boolean
Activate (or not) the beneficiary.


 
display
boolean
Display (or not) the beneficiary to the end-user (unusable by end-user).


 
friendlyName
string  [ 1 .. 255 ] characters 
Friendly name given to the beneficiary.


 
Responses 
200
OK


202
Waiting SCA


400
Bad Request


401
Unauthorized


403
Forbidden


404
Not Found


patch/api/partner/beneficiaries/{beneficiaryId}
Request samples 
application/json
{
  • "active": true,
  • "display": true,
  • "friendlyName": "string"
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
➔ Next to Transaction