diff --git a/_entities.md b/_entities.md index 40ac521..82f28bc 100644 --- a/_entities.md +++ b/_entities.md @@ -260,10 +260,12 @@ network | The network of the transaction (`uphold` for internal transaction normalized | The transaction details in USD. See [Normalized](#normalized). origin | The sender of the funds. See [Origin](#origin). params | Other parameters of this transaction. See [Parameters](#parameters). -priority | The priority of the transaction. Possible values are `normal` and `fast`. -reference | A reference code assigned to the transaction. Can be any string, up to 100 characters. This is not exposed to the user; a possible use case is to reference an external ID in another system. -status | The current status of the transaction. Possible values are `pending`, `processing`, `cancelled`, `failed` and `completed`. -type | The nature of the transaction. Possible values are `deposit`, `transfer` and `withdrawal`. +priority | The priority of the transaction. Possible values are `normal` and `fast`. +reference | A reference code assigned to the transaction. Can be any string, up to 100 characters. This is not exposed to the user; a possible use case is to reference an external ID in another system. +requirements | An array of requirement codes that must be fulfilled before the transaction can be committed. May include `user-subject-to-extended-travel-rule`. Absent when no requirements apply. +requirementsDetails | An object with additional details about each requirement. See [Requirements Details](#requirements-details). Absent when no requirements apply. +status | The current status of the transaction. Possible values are `pending`, `processing`, `cancelled`, `failed` and `completed`. +type | The nature of the transaction. Possible values are `deposit`, `transfer` and `withdrawal`. + ### Step 2: Commit Transaction diff --git a/_travelrule.md b/_travelrule.md new file mode 100644 index 0000000..d8058c3 --- /dev/null +++ b/_travelrule.md @@ -0,0 +1,177 @@ +# Travel Rule + +The Travel Rule is a regulatory requirement that mandates Virtual Asset Service Providers (VASPs) to collect and transmit originator and beneficiary information for cryptocurrency transfers above a certain threshold. +When a deposit or a withdrawal triggers this requirement, Uphold issues a request for information that must be fulfilled before the transfer can proceed. + +There are two ways to retrieve the details of a travel rule request, depending on the context: + +- **Deposits**: the transaction is already present and may have a pending travel rule request associated with it. Use [Get Travel Rule Details for a Transaction](#get-travel-rule-details-for-a-transaction) with the `transactionId` to retrieve those details. +- **Withdrawals**: when [creating a quote](#step-1-create-transaction), the transaction response may include a `requirementsDetails.requestForInformationId` if the Travel Rule applies. Use [Get Travel Rule Details](#get-travel-rule-details) with that ID to retrieve the details, then [Submit Travel Rule Information](#submit-travel-rule-information) before [committing the quote](#step-2-commit-transaction). + +## Get Travel Rule Details for a Transaction + +```bash +curl https://api.uphold.com/v0/me/travel-rule/transactions/2c326b15-7106-48be-a326-06f19e69746b/request \ + -H "Authorization: Bearer " +``` + +> The above command returns the following JSON: + +```json +{ + "amount": "1500.00", + "currency": "USDT", + "formSchema": { + "properties": { + "beneficiaryAccountNumber": { + "title": "Beneficiary account number", + "type": "string" + }, + "beneficiaryAddress": { + "title": "Beneficiary address", + "type": "string" + }, + "beneficiaryCountry": { + "title": "Beneficiary country", + "type": "string" + }, + "beneficiaryName": { + "title": "Beneficiary name", + "type": "string" + } + }, + "required": [ + "beneficiaryName", + "beneficiaryAddress", + "beneficiaryCountry", + "beneficiaryAccountNumber" + ], + "type": "object" + }, + "threshold": "1000.00" +} +``` + +Retrieves the details of the pending travel rule request associated with a deposit transaction, including the transaction amount, the applicable regulatory threshold, and the form schema describing the information that must be submitted. + +### Request + +`GET https://api.uphold.com/v0/me/travel-rule/transactions/:transactionId/request` + + + + +### Response + +Returns an object with the following properties: + +Property | Description +------------- | ----------- +amount | The transaction amount that triggered the travel rule requirement. +currency | The currency of the transaction. +formSchema | A JSON Schema object describing the fields the user must provide via the [Submit Travel Rule Information](#submit-travel-rule-information) endpoint. +threshold | The regulatory threshold above which the travel rule applies, in the same currency as `amount`. + +## Get Travel Rule Details + +```bash +curl https://api.uphold.com/v0/me/travel-rule/requests/a4e5e6f7-1234-5678-abcd-ef0123456789 \ + -H "Authorization: Bearer " +``` + +> The above command returns the following JSON: + +```json +{ + "amount": "1500.00", + "currency": "USDT", + "formSchema": { + "properties": { + "beneficiaryAccountNumber": { + "title": "Beneficiary account number", + "type": "string" + }, + "beneficiaryAddress": { + "title": "Beneficiary address", + "type": "string" + }, + "beneficiaryCountry": { + "title": "Beneficiary country", + "type": "string" + }, + "beneficiaryName": { + "title": "Beneficiary name", + "type": "string" + } + }, + "required": [ + "beneficiaryName", + "beneficiaryAddress", + "beneficiaryCountry", + "beneficiaryAccountNumber" + ], + "type": "object" + }, + "threshold": "1000.00" +} +``` + +Retrieves the details of a pending travel rule request for a withdrawal, using the `requestForInformationId` returned as part of the quote response. + +### Request + +`GET https://api.uphold.com/v0/me/travel-rule/requests/:requestForInformationId` + + + + +### Response + +Returns an object with the following properties: + +Property | Description +------------- | ----------- +amount | The transaction amount that triggered the travel rule requirement. +currency | The currency of the transaction. +formSchema | A JSON Schema object describing the fields the user must provide via the [Submit Travel Rule Information](#submit-travel-rule-information) endpoint. +threshold | The regulatory threshold above which the travel rule applies, in the same currency as `amount`. + +## Submit Travel Rule Information + +```bash +curl https://api.uphold.com/v0/me/travel-rule/requests/a4e5e6f7-1234-5678-abcd-ef0123456789 \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ "beneficiaryAccountNumber": "0x1234abcd", "beneficiaryAddress": "123 Main St", "beneficiaryCountry": "US", "beneficiaryName": "Jane Doe" }' +``` + +Submits the originator or beneficiary information required to fulfill a pending travel rule request. +The fields in the request body must conform to the `formSchema` returned by the [Get Travel Rule Details for a Transaction](#get-travel-rule-details-for-a-transaction) or [Get Travel Rule Details](#get-travel-rule-details) endpoints. +For withdrawals, this must be submitted before [committing the quote](#step-2-commit-transaction). + +### Request + +`POST https://api.uphold.com/v0/me/travel-rule/requests/:requestForInformationId` + + + + +The request body must be a valid JSON object whose properties satisfy the `formSchema` associated with the given `requestForInformationId`. +A 400 HTTP error is returned if the request body is not a valid JSON object. + +### Response + +Returns HTTP status code `204` with an empty body upon success.