Skip to navigation
EchoIntents

Create an Intent

Declare a transaction authorization processed by a third-party PSP

This endpoint allows you to declare a payment authorized by a third-party PSP. Once AUTHORIZED (as shown by the Status in the response), the Intent’s LineItems can be:

In a mixed-basket flow, you can also use this endpoint to add LineItems to an existing Intent by sending the same ExternalData.ExternalProviderReference as the existing Intent.

In a hybrid flow, where the ExternalProviderName is Mangopay, you can define the LineItems.SplitOriginWalletId in the Intent, otherwise it must be defined on POST Create an Intent Split.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

If your platform is using a proxy to take SCA-triggering action on behalf of users, you also need to integrate mTLS authentication and use the api-mtls base URL.

Path parameters

ClientIdstringRequired
Platform's API account identifier, associated with the API key.

Request

This endpoint expects an object.
AmountintegerRequired

The full amount authorized in the Intent, which must equal the sum of the total amounts of all LineItems.

CurrencystringRequired
The currency of the intent.
ExternalDataobjectRequired

Information about the transaction authorization processed by the third-party PSP.

LineItemslist of objectsRequired

Information about the items purchased in the transaction. A maximum of 100 line items can be created per Intent.

The sum of all line item amounts must equal the Intent Amount value. The total for each line items is calculated as ((UnitAmount x Quantity) - DiscountAmount), which is shown in the TotalLineItemAmount returned. The TaxAmount is indicative and included in the UnitAmount.

The sum of all line item Seller.FeesAmount values must equal the Intent PlatformFeesAmount value.

PlatformFeesAmountintegerOptional

The amount of fees to be diverted to the platform’s Fees Wallet when the Intent is split. This value can be overridden when the Split is created.

The PlatformFeesAmount value must the sum of all line item Seller.FeesAmount values.

BuyerobjectOptional
Information about the buyer.
TagstringOptional

Max. length: 255 characters

Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: "{\"id_1\":AB123,\"id_2\":DE456}".

Response

Success
IdstringOptional
The unique identifier of the intent.
AmountintegerOptional

The full amount authorized in the Intent, which must equal the sum of the total amounts of all LineItems.

AvailableAmountToSplitintegerOptional
The remaining amount of the Intent that can be split and transferred to the sellers' wallets.
UnfundedAmountintegerOptional
The amount needing to be settled to the Platform's technical wallet before the Intent Splits can be executed.
CurrencystringOptional
The currency of the intent.
PlatformFeesAmountintegerOptional

The amount of fees to be diverted to the platform’s Fees Wallet when the Intent is split. This value can be overridden when the Split is created.

The PlatformFeesAmount value must the sum of all line item Seller.FeesAmount values.

StatusstringOptional

The status of the Intent, as declared by the platform through Intent Captures, Refunds (and reversals), or Disputes (and decisions). Where partial actions occur, the top-level Intent Status may differ from the Status of Intent LineItems.

Intent Status values:

  • AUTHORIZED – The Intent Amount was authorized for acquisition by the PSP and can be captured or canceled.
  • PARTIALLY_CAPTURED – Part of the Intent Amount from one or more LineItems was captured. The other parts are either still available for capture or cancel.
  • CAPTURED – All of the Intent Amount was captured. Part of it may have been subsequently refunded or disputed.
  • CANCELLED – All of the Intent Amount was canceled.
  • REFUNDED – All of the CapturedAmount of all LineItems was refunded.
  • REFUND_REVERSED – The refund could not be completed and the funds were returned to the platform.
  • DISPUTED – All of the CapturedAmount of all LineItems was disputed.
  • DEFENDED – The dispute is being defended by the platform.
  • DISPUTED_WON – The dispute was resolved in favor of the platform.
  • DISPUTED_LOST – The dispute was resolved against the platform.
NextActionsstringOptional
The possible next actions on the intent.
ExternalDataobjectOptional

Information about the transaction authorization processed by the third-party PSP.

BuyerobjectOptional
Information about the buyer.
LineItemslist of objectsOptional

Information about the items purchased in the transaction. A maximum of 100 line items can be created per Intent.

The sum of all line item amounts must equal the Intent Amount value. The total for each line items is calculated as ((UnitAmount x Quantity) - DiscountAmount), which is shown in the TotalLineItemAmount returned. The TaxAmount is indicative and included in the UnitAmount.

The sum of all line item Seller.FeesAmount values must equal the Intent PlatformFeesAmount value.

TagstringOptional

Max. length: 255 characters

Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: "{\"id_1\":AB123,\"id_2\":DE456}".

CreationDateintegerOptional

Unix timestamp (UTC) of the date and time the object was created.

ExecutionDateintegerOptional

Unix timestamp (UTC) of the date and time the Intent moved to AUTHORIZED.

Errors

400
Bad Request Error