Card Issuance

Retrieves the list of available card programs and their details.

Card program: a Card Program is what Wise calls all the cards you will be issuing with us, grouped by product type and by issuing country.

Issuing country: the country where your card is created.

Product type: the type of card we are issuing on your behalf (consumer, corporate, digital, physical, etc.).

POST /v3/spend/profiles/{{profileId}}/card-orders

Orders a new card for a given profile. The card program should come from the list of available card programs.

The lifetimeLimit parameter is the maximum amount that can be spent with the card for the entire lifetime of the card. The lifetime limit currency is the card's default currency defined in the card program. The default lifetime limit value is 0, which means the card cannot be used until the lifetime limit is updated.

The billing address fields (firstLine, secondLine, thirdLine, city, state) all have a maximum length of 30 characters.

Please also note that this call needs an extra field in the header called "X-idempotence-uuid". This should be generated and used for any subsequent retry call in the case that the initial POST fails.

The returned response contains the status. The possible status values are:

• PLACED - The profile is not verified. The digital card will be generated once the profile is verified.
• REQUIREMENTS_FULFILLED - The card is being generated, which usually takes less than one second.
• CARD_DETAILS_CREATED - The card has been generated. The completion of a digital card order only takes a few extra milliseconds.
• COMPLETED - The card has been generated and the card order has been completed.
• CANCELLED - The card order has been canceled. This can happen if you ask Wise customer support team to cancel a card order.

Response

Returns a card order.

GET /v3/spend/profiles/{{profileId}}/card-orders?pageSize=10&pageNumber=1

The following parameters are optional:

• pageSize - the maximal number of requested card orders (used for pagination). This parameter has to be between 10 and 100 inclusive. If ommitted the default value 10 is used.
• pageNumber - the requested page number starting from 1 (used for pagination). This parameter has to be equal or greater than 1. If ommitted the default value of 1 is used.

Both parameters are optional and if not provided their default values will be used.

Response

The returned response contains 2 elements:

• totalCount - the total number of card orders, this number is never affected by the given pageSize or pageNumber parameters
• cardOrders - the list of card orders starting from the given pageNumber (please keep in mind that the size of this list is limited by the given pageSize parameter with a default value of 10)

GET /v3/spend/profiles/{{profileId}}/card-orders/{{cardOrderId}}

Retrieves the details of a particular card order given its id.

Response

Returns a card order.

GET /v3/spend/profiles/{{profileId}}/cards?pageSize=10&pageNumber=1

Retrieves the details of all cards that belong to a given profile.

The following parameters are optional:

• pageSize - the maximal number of requested cards (used for pagination). This parameter has to be between 10 and 100 inclusive. If omitted the default value 10 is used.
• pageNumber - the requested page number starting from 1 (used for pagination). This parameter has to be equal or greater than 1. If omitted the default value of 1 is used.

Both parameters are optional and if not provided their default values will be used.

Response

The returned response contains 2 elements:

• totalCount - the total number of cards, this number is never affected by the given pageSize or pageNumber parameters
• cards - the list of cards starting from the given pageNumber (please keep in mind that the size of this list is limited by the given pageSize parameter with a default value of 10)

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}

Retrieves the details of one card given its id (also referred as a card token).

Response

Returns a card object.

PUT /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/status

Modifies the card status, where the possible new status values are:

• ACTIVE - the card is active and usable
• FROZEN - the card is temporarily frozen resulting in all authorisation requests to be declined
• BLOCKED - the card is irreversibly blocked and is no longer usable

Response

Returns a card object.

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits

Retrieves the card limits

Response

Returns a set of limits for the card sent.

Retrieves the profile limits.

Limit details are defined as follows:

PATCH /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits

Set or change card spending limits. By default, a new card will have a lifetime limit set to 0.

Response

Returns a 200 response - No Content

DELETE /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-limits/lifetime

Delete the lifetime limit.

Response

Returns a 200 response - No Content

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions

Retrieves the card permissions

Response

Returns a set of permissions for the card sent.

The possible type values are:

• ECOM
• POS_CHIP
• POS_MAGSTRIPE
• ATM_WITHDRAWAL
• POS_CONTACTLESS
• MOBILE_WALLETS

PATCH /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/spending-permissions

Enable or disable a card permission

The possible type values are:

• ECOM
• POS_CHIP
• POS_MAGSTRIPE
• ATM_WITHDRAWAL
• POS_CONTACTLESS
• MOBILE_WALLETS

Response

Returns a 200 response - No Content

GET /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/transactions?pageSize=10&pageNumber=1&fromTransactionDate=2022-11-01&toTransactionDate=2022-11-15

You can also use the card transaction webhook instead.

You can follow this guide to simulate various card transactions in the sandbox environment.

Retrieves the card transactions list.

The following parameters are optional:

• pageSize - the maximal number of requested card orders (used for pagination). This parameter has to be between 10 and 100 inclusive. If ommitted the default value 10 is used.
• pageNumber - the requested page number starting from 1 (used for pagination). This parameter has to be equal or greater than 1. If ommitted the default value of 1 is used.
• fromTransactionDate - the starting date of the date filter. The date format is YYYY-MM-DD.
• toTransactionDate - the end date of the date filter. The date format is YYYY-MM-DD.

The possible type values are:

• ACCOUNT_CREDIT - Receiving money on the card, excluding Visa OCT or Mastercard MoneySend
• ACCOUNT_FUNDING - Sending money to another card or e-wallet
• CASH_ADVANCE - Cash disbursement
• CASH_WITHDRAWAL - ATM withdrawal
• CHARGEBACK - Currently unused. Reserved for future use.
• CREDIT_TRANSACTION - Visa OCT and Mastercard MoneySend
• ECOM_PURCHASE - Online purchase
• POS_PURCHASE - Purchase via a POS Terminal
• REFUND - Partial or full refund of an existing card transaction

The possible state values are:

• IN_PROGRESS - The transaction has been authorized but not captured.
• COMPLETED - The transaction has been captured and/or settled.
• DECLINED - The transaction has been declined.
• CANCELLED - The transaction has been cancelled.
• UNKNOWN - Default fallback status if the state can't be confirmed.

When a refund happens, a separate transaction will be added with a REFUND transaction type.

Response

Returns a set of transactions for the card.

GET /v3/spend/profiles/{{profileId}}/cards/transactions/{{transactionId}}

Retrieve a card transaction by transaction id.

The possible type values are:

• ACCOUNT_CREDIT - Receiving money on the card, excluding Visa OCT or Mastercard MoneySend
• ACCOUNT_FUNDING - Sending money to another card or e-wallet
• CASH_ADVANCE - Cash disbursement
• CASH_WITHDRAWAL - ATM withdrawal
• CHARGEBACK - Currently unused. Reserved for future use.
• CREDIT_TRANSACTION - Visa OCT and Mastercard MoneySend
• ECOM_PURCHASE - Online purchase
• POS_PURCHASE - Purchase via a POS Terminal
• REFUND - Partial or full refund of an existing card transaction

The possible state values are:

• IN_PROGRESS - The transaction has been authorized but not captured.
• COMPLETED - The transaction has been captured and/or settled.
• DECLINED - The transaction has been declined.
• CANCELLED - The transaction has been cancelled.
• UNKNOWN - Default fallback status if the state can't be confirmed.

When a refund happens, a separate transaction will be added with a REFUND transaction type.

PUT /v3/spend/profiles/{{profileId}}/cards/{{cardToken}}/phone-number

Update phone number of a card. The new phone number must be a valid phone number.

Response

Returns a 200 response

GET /v3/spend/profiles/{{profileId}}/dispute-form/reasons

Retrieves the list of possible reasons for submitting a dispute.

Response

Returns a set of dispute objects.

GET /v3/spend/profiles/{{profileId}}/dispute-form/flows/{{scheme}}/{{reason}}?transactionId={{transactionId}}

Retrieves the JSON for initiating the dispute flow. The returned result can be used to generate the dispute flow UI using the Wise's open-source Dynamic Flows framework . The Dynamic Flows Framework will generate UI according to the received JSON and will handle the rest of the multi-step dispute submission including the generation of the subsequent pages (if needed) and the actual submission of the dispute and all the relevant documents.

An example of using a Dispute flow can be found here.

Because the calls to the above endpoint are authorised they cannot be made from the Dynamic Flows JavaScript framework directly (from the browser), but instead must be proxied by the partner with the added auth headers. Therefore, a partner is expected to implement 2 additional internal endpoints:

1. Get Dynamic Form Page:

GET https://{{yourApiUrl}}/v3/spend/profiles/{{profileId}}/dispute-form/flows/step/{{scheme}}/{{reason}}?transactionId={{transactionId}}

The implementation of this endpoint is expected to redirect the call to:

POST https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/dispute-form/flows/step/{{scheme}}/{{reason}}

This implementation is also expected to add an email of the disputer and the ID of the disputed transaction. The email is added in order to allow direct communication with a person who knows the dispute details. The body of the POST request forwarded to Wise should be of the following form:

{
    "email": "abc@def.com",
    "transactionId": "<transaction id>"
}

2. Post Dynamic Form Results:

The final step of the dispute flow will have to submit all the collected data to Wise. However, since Authorization header is required, a partner is expected to implement the following endpoint (please note the absence of a step in the URL path):

POST https://{{yourApiUrl}}/v3/spend/profiles/{{profileId}}/dispute-form/flows/{{scheme}}/{{reason}}

The request body will be generated by Dynamic Forms. The implementation of this endpoint is expected to redirect the call to:

POST https://api.sandbox.transferwise.tech/v3/spend/profiles/{{profileId}}/dispute-form/flows/{{scheme}}/{{reason}}

The response to this last call of the dynamic flow will include x-df-exit: true HTTP header. This header is used by the JavaScript framework to add an option to exit the dynamic flow and redirect the user to a different page (or exit a WebView depending on the client's implementation). In order to intercept the last page response on the frontend onClose function should be added to JavaScript, for example:

const onClose = () => {
  console.log("DF is exiting");
  window.location.href = "https://www.google.com/";
};

Both endpoints are expected to proxy the requests with the added auth headers. In order to redirect the Dynamic Flows JavaScript library to your domain please use baseUrl or fetcher as part of the dynamic flows setup.

The Dynamic Form CSS styles can be overriden. An example of a Dispute flow with custom CSS can be found here.

The sensitive card details endpoint allows you to retrieve card data such as Primary Account Number, expiry date, CVV and PIN.

Wise is a PCI DSS compliant provider, and stores all of your Cards API data securely. The scope for PCI compliance depends on your use case and will impact how you integrate with Cards API.

It is possible to define which card transactions will be approved or declined by adding authorisation rules. Currently the only supported rules are based on MCC (Merchant Category Code) and transaction currency. An example list of MCC can be found here: https://www.citibank.com/tts/solutions/commercial-cards/assets/docs/govt/Merchant-Category-Codes.pdf. The currencies should be specified in ISO 4217 alphabetic format, for example USD.

The rules management is done as follows:

A rule is an instruction to Wise that dictates which transactions should be declined or approved. Defining a rule has no practical implication until it is applied to a particular CARD/PROFILE or every card, which is achieved by applying a rule to a PARTNER.

The id of a rule is unique and will refer to this rule in any further call.

The parameters for the creation of rules are as follows:

Deletes an existent rule. Rule deletion is only possible if a rule does not apply to any scope. If a rule was already applied to a scope, unapply should be invoked prior to the rule deletion.

HTTP response code should be assessed to verify the success or failure of this call.

Lists all the defined rules. The list will include all the rules whether these were applied to a scope or not.

The following endpoint applies a defined rule to a give scope (card/profile or partner). This will result in a rule being evaluated against every incoming card authorisation request for the given CARD/PROFILE/PARTNER.

HTTP response code should be assessed to verify the success or failure of this call.

The parameters for the apply endpoint are as follows:

This endpoint reverses the apply endpoint and it's invocation will result in removing a rule from a given scope.

HTTP response code should be assessed to verify the success or failure of this call.

The parameters for the unapply endpoint are as follows:

Returns the list of all the active authorisation rules and the scopes they have been applied to.