> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-platform-1/api-reference/payments/beneficiary-management-apis.md).

# Beneficiary Management APIs

## POST /api/v1/beneficiary

> Create a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary":{"post":{"tags":["BeneficiaryController"],"description":"Create a beneficiary","operationId":"BeneficiaryController::createBeneficiary","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"Beneficiary"}}}}
```

## GET /api/v1/beneficiary/coordinates/{id}

> Get a coordinate by id

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/coordinates/{id}":{"get":{"tags":["BeneficiaryCoordinateController"],"description":"Get a coordinate by id","operationId":"BeneficiaryCoordinateController::getCoordinatesById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/coordinates/{id}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coords"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_coords":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"Records an IBAN, account number, etc. for an account."},"entity":{"$ref":"#/components/schemas/cda_entity_schema_entity_entity","description":"The persisted entity. Note that this field is, in general, mutable."},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the beneficiary coordinates, generated on creation."}},"required":["id","entity","coordinates"],"title":"BeneficiaryCoords"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cda_entity_schema_entity_entity":{"type":"object","properties":{"affiliation":{"type":"string","enum":["CUSTOMER","INTERNAL","EXTERNAL"],"description":"Describes the relationship the entity has with XYB."},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/cda_entity_schema_entity_aspect_entity_aspect"},"description":"The list of aspects associated with the Entity"},"reference":{"type":"string","description":"Possibly a company number, a service identifier or an employee code"},"type":{"type":"string","enum":["INDIVIDUAL","ORGANIZATION","COLLECTIVE","VIRTUAL"],"description":"The type of the entity; determines how any entity reference is interpreted."}},"required":["type","affiliation"],"title":"Entity","description":"Something or someone who owns an account, or who interacts directly or indirectly with the system."},"cda_entity_schema_entity_aspect_entity_aspect":{"type":"object","properties":{"aspect":{"$ref":"#/components/schemas/cda_entity_schema_entity_aspect_aspect","description":"Concrete aspect"},"identifier":{"type":"string","format":"uuid","description":"A unique identifier for the aspect"},"relation":{"type":"string","description":"May be used to disambiguate aspects of the same type associated with the same entity"}},"required":["identifier","aspect"],"title":"EntityAspect"},"cda_entity_schema_entity_aspect_aspect":{"type":"object","properties":{},"title":"Aspect"}}}}
```

## POST /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates

> Get additional attributes for a coordinate

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates":{"post":{"tags":["BeneficiaryDynamicCoordinateController"],"description":"Get additional attributes for a coordinate","operationId":"BeneficiaryDynamicCoordinateController::createContactAccountDynamic","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request":{"type":"object","properties":{"alias":{"type":"string"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_coordinates"},"currency":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"required":["currency"],"title":"CreateBeneficiaryCoordinateDynamicRequest"},"cac_bnficiary_schema_dynamic_coordinates":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"secondary_identification":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicCoordinates"},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}}
```

## PATCH /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId}

> Update a coordinate for a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId}":{"patch":{"tags":["BeneficiaryDynamicCoordinateController"],"description":"Update a coordinate for a beneficiary","operationId":"BeneficiaryDynamicCoordinateController::updateContactAccountDynamic","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request":{"type":"object","properties":{"alias":{"type":"string"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_coordinates"},"currency":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"required":["currency"],"title":"CreateBeneficiaryCoordinateDynamicRequest"},"cac_bnficiary_schema_dynamic_coordinates":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"secondary_identification":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicCoordinates"},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}}
```

## POST /api/v1/beneficiary/identity/{identityReference}/

> Create beneficiary with identity

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/":{"post":{"tags":["BeneficiaryIdentityController"],"description":"Create beneficiary with identity","operationId":"BeneficiaryIdentityController::createBeneficiaryWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}}
```

## POST /api/v1/beneficiary/identity/{identityReference}/sync

> Sync beneficiaries

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/sync":{"post":{"tags":["BeneficiaryIdentityController"],"description":"Sync beneficiaries","operationId":"BeneficiaryIdentityController::syncContactBeneficiaries","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_sync_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/sync"}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_sync_request":{"type":"object","properties":{"contact_hashes":{"type":"array","items":{"type":"string"},"uniqueItems":true,"description":"The contact hashes of a customer phonebook that will be synced."}},"required":["contact_hashes"],"title":"BeneficiarySyncRequest","description":"Request to sync contacts of a customer phonebook with list of beneficiaries."}}}}
```

## POST /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}

> Verify OTP for a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}":{"post":{"tags":["BeneficiaryVerificationController"],"description":"Verify OTP for a beneficiary","operationId":"BeneficiaryVerificationController::verifyCoordinate","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"verificationUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coordinate_verification_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coordinate_verification_response"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_coordinate_verification_request":{"type":"object","properties":{"otp":{"type":"string","description":"One time passcode for beneficiary coordinate verification"}},"required":["otp"],"title":"BeneficiaryCoordinateVerificationRequest"},"cac_bnficiary_schema_beneficiary_coordinate_verification_response":{"type":"object","properties":{"beneficiary_coordinate_uuid":{"type":"string","format":"uuid"},"beneficiary_uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["VERIFIED","PENDING","FAILED"]},"verification_uuid":{"type":"string","format":"uuid"}},"required":["status","beneficiary_uuid","beneficiary_coordinate_uuid","verification_uuid"],"title":"BeneficiaryCoordinateVerificationResponse"}}}}
```

## PATCH /api/v1/beneficiary/identity/{identityReference}/{idRef}

> Update beneficiary with identity

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}":{"patch":{"tags":["BeneficiaryIdentityController"],"description":"Update beneficiary with identity","operationId":"BeneficiaryIdentityController::updateBeneficiaryWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}}
```

## POST /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/

> Add a coordinate to a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/":{"post":{"tags":["BeneficiaryIdentityCoordinateController"],"description":"Add a coordinate to a beneficiary","operationId":"BeneficiaryIdentityCoordinateController::createCoordinateWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pay_entry_schema_account_coords"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_account_schema_account_coordinates"}}}}}}}},"components":{"schemas":{"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_account_schema_account_coordinates":{"type":"object","properties":{"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"Records an IBAN, account number, etc. for an account."},"external":{"type":"object","additionalProperties":{"type":"string"},"description":"Strictly optional external information for account coordinates."},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the account, generated on creation."},"tags":{"type":"array","items":{"type":"string"},"description":"Strictly optional application-scoped tags for the account coordinates."}},"required":["id","coordinates"],"title":"AccountCoordinates"}}}}
```

## DELETE /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}

> Delete a coordinate from a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}":{"delete":{"tags":["BeneficiaryIdentityCoordinateController"],"description":"Delete a coordinate from a beneficiary","operationId":"BeneficiaryIdentityCoordinateController::deleteCoordinateWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}"}}}}}}
```

## POST /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category}

> Add a category to a coordinate

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category}":{"post":{"tags":["BeneficiaryIdentityCoordinateController"],"description":"Add a category to a coordinate","operationId":"BeneficiaryIdentityCoordinateController::addCoordinatePaymentCategory","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"category","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category}"}}}}}}
```

## DELETE /api/v1/beneficiary/{idRef}

> Delete a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}":{"delete":{"tags":["BeneficiaryController"],"description":"Delete a beneficiary","operationId":"BeneficiaryController::deleteBeneficiary","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}"}}}}}}
```

## PATCH /api/v1/beneficiary/{idRef}

> Update a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}":{"patch":{"tags":["BeneficiaryController"],"description":"Update a beneficiary","operationId":"BeneficiaryController::updateBeneficiary","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}}
```

## POST /api/v1/beneficiary/{idRef}/address

> Add an address to a beneficiary

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/address":{"post":{"tags":["BeneficiaryAddressController"],"description":"Add an address to a beneficiary","operationId":"BeneficiaryAddressController::addAddress","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_address":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id"],"title":"BeneficiaryAddress"}}}}
```

## POST /api/v1/fields/{identityReference}/payment/validate

> Validate payment creation

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/fields/{identityReference}/payment/validate":{"post":{"tags":["PaymentFieldsController"],"description":"Validate payment creation","operationId":"PaymentFieldsController::validatePaymentCreation","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_payment_creation_validation"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/fields/{identityReference}/payment/validate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_payment_payment_validation_error_response"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_payment_creation_validation":{"type":"object","properties":{"beneficiary_account_uuid":{"type":"string","format":"uuid"},"beneficiary_uuid":{"type":"string","format":"uuid"},"currency":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["beneficiary_uuid","beneficiary_account_uuid","currency","fields"],"title":"BeneficiaryPaymentCreationValidation"},"cac_bnficiary_schema_payment_payment_validation_error_response":{"type":"object","properties":{"violations":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_payment_localised_payment_field_violation"},"uniqueItems":true}},"required":["violations"],"title":"PaymentValidationErrorResponse"},"cac_bnficiary_schema_payment_localised_payment_field_violation":{"type":"object","properties":{"key":{"type":"string"},"localized_message":{"type":"string"}},"required":["key","localized_message"],"title":"LocalisedPaymentFieldViolation"}}}}
```

## POST /api/v1/sync/interrupt

> Interrupt the synchronization process

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/sync/interrupt":{"post":{"tags":["CustomerUpdateSyncController"],"description":"Interrupt the synchronization process","operationId":"CustomerUpdateSyncController::interruptSync","responses":{"200":{"description":"Response to /api/v1/sync/interrupt"}}}}}}
```

## POST /api/v1/sync/manual

> Manually initiate the synchronization process

```json
{"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/sync/manual":{"post":{"tags":["CustomerUpdateSyncController"],"description":"Manually initiate the synchronization process","operationId":"CustomerUpdateSyncController::doManualSyn","responses":{"200":{"description":"Response to /api/v1/sync/manual"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xyb.co/xyb-platform-1/api-reference/payments/beneficiary-management-apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.