Notre objet paiement dispose d'une variable custom_data permettant de spécifier un ensemble de valeurs libres en format JSON.

Cas d'usages

Vos données

Cela vous permet de faire transiter des informations provenant de vos systèmes pour relier les paiements Alma à vos propres objets.

Par exemple, Alma utilise custom_data dans ses modules d'intégration e-commerce pour conserver l'ID de base de données du panier ou de la commande pour lequel le paiement Alma a été créé, ce qui aide à la validation finale du paiement lors du retour client ou du callback IPN.

Ces données peuvent aussi être remontées dans vos exports comptables, vous pouvez donc également y intégrer des données opérationnelles telles que des ID magasin, ID vendeur, ou toute autre information qui pourra faciliter la réconciliation des transactions.

Données produits

Notre API accepte un objet cart dans les données de création du paiement, avec les informations suivantes :

FieldName	Data type	Required	Comment
items	array of object	required
items.sku	string	required	product SKU
items.vendor	string	optional	product vendor/brand
items.title	string		product name
items.variant_title	string	optional	product variant name
items.quantity	integer	required	product quantity
items.unit_price	integer	optional	product price in cents
items.line_price	integer	required	unit x quantity price in cents
items.is_gift	boolean	optional	is product being offered
items.categories	array of strings	required	product categories
items.url	string	optional	product page URL
items.picture_url	string	required	product picture URL
items.requires_shipping	boolean	optional	whether product is physical
items.taxes_included	boolean	optional	whether price is taxes included
items.marketplace_seller	object	optional	only required for marketplaces (see below)
discounts	array of object	optional	discounts applied to the purchase
discounts.title	string	optional	marketing campaign name
discounts.amount	integer	required	discounted amount in cents

{
  "payment": {
    ...
    "cart": {
      "items": [
        {
          "sku”: “product SKU - optional”,
          "vendor": "product vendor/brand - optional",
          "title": "product name - required",
          "variant_title": “product variant name - optional",
          "quantity": <product quantity (int) - required>,
          "unit_price": <product price in cents (int) - optional>,
          "line_price": <unit * quantity price in cents (int) - required>,
          "is_gift": <is product being offered (boolean) - optional>,
          "categories": ["product", "categories", "optional"],
          "url": "product page URL - optional",
          "picture_url": "product picture URL - required",
          "requires_shipping": <whether product is physical (boolean) - optional>,
          "taxes_included": <whether price is taxes included - optional>
        },
        ...
      ],
      "discounts": [  // optional - discounts applied to the purchase
        {
           "title": "marketing campaign name - optional",
           "amount": <discounted amount in cents (int) - required>
         },
         ...
       ]
      },
    ...
  }
}

Données spécifiques pour les marketplaces

Structure des données pour items.marketplace_seller:

FieldName	Data type	Requirement	Comment
account_id	string	required
country	string / ISO 3166-1 alpha-2 format	required
account_created	string / ISO 8601	optional
account_type	string	required
business	object	required if `account_type = business`
business.company_name	string	required
business.business_id_number	string	required
business.website	string	optional
individual	object	required if `account_type = individual`
individual.full_name	string	required
individual.email	string	required
rating	float (0.0 to 5.0)	optional	Seller score/rating on the marketplace based on user reviews

Données spécifiques à l'industrie Tourisme & Loisirs

Si vous êtes en mesure de les fournir, notre algorithme de scoring utilise plusieurs données spécifiques à l'industrie Tourisme & Loisirs permettant de mieux scorer vos clients.

Spécifications

Nous vous invitons à les renseigner dans un sous-objet scoring de cette façon:

Field Name	Sub field name	Data Type	Format	Exemple	Comment	Presence	Apply to travel (flight, cruise)	Apply to hospitality	Apply to others (ticketing, ...)
`departure_date`		date	ISO 8601	2023-02-27	date of departure or beginning of the event/activity	mandatory	Yes	Yes	Yes
`return_date`		date	ISO 8601	2023-02-27	date of return or end of the event/activity	optional	Yes	Yes	Yes
`destination_name`		string	60 characters max		city at arrival	optional	Yes	Yes	Yes
`destination_country`		string	ISO 3166-1 alpha-2	FR	country of arrival	mandatory	Yes	Yes	Yes
`refund_policy`		string	60 characters max	"exchangeable", "refundable", "both", "none"	refund or exchange policy of the service	mandatory	Yes	Yes	Yes
`passengers`	`adult_count`	int		2	number of adults on the booking	mandatory	Yes	Yes	Yes
	`children_count`	int	no specified age threshold		number of children on the booking	mandatory	Yes	Yes	Yes
	`infant_count`	int	no specified age threshold		number of infant on the booking	mandatory	Yes	Yes	Yes
`hosting`	`room_type`	string		"single", "double", "suite"...	type of room	optional		Yes
	`nights`	int		7	number of nights	optional		Yes
	`category`	int	1 to 5		hostel category	desired		Yes
`flight`	`main_departure_company`	string	3 characters maximum	"AF" for Air France	company name for the firstflight	mandatory	Yes
	`departure_airport`	string	IATA code on 3 characters		code of the departure airport	desired	Yes
	`arrival_airport`	string	IATA code on 3 characters		code of the arrival airport	desired	Yes
	`has_transfers`	boolean		"true" or "false"	true if there are at least one stopover. false for direct flights	optional	Yes
	`round_trip`	boolean		"true" or "false"		optional	Yes
	`travel_class`	string		"economy", "business" or "first"		desired	Yes
`insurance`	`name`	string	150 characters maximum	"Sans Assurance" if no insurance	type of the insurance	mandatory	Yes	Yes	Yes
	`price`	int	amount in cents.	58.12 => 5812	price of the insurance	desired	Yes	Yes	Yes
`activity`		string		"concert", "rafting", ...	type of activity or service	mandatory			Yes
`loyalty_program`	`has_loyalty`	boolean		"true" or "false"	`true` if the consumer benefits from any kind of loyalty program (excluding welcome offers)	mandatory	Yes	Yes	Yes
	`name`	string	60 characters max		Name of the loyalty program	desired	Yes	Yes	Yes

Par mandatory nous souhaitons disposer de cette information utilisée pour augmenter votre taux de conversion en affinant la gestion du risque.
Par desired nous souhaiterions disposer de cette information qui nous semble pertinente dans la gestion du risque.
Par optional nous pensons que ces données pourraient potentiellement être intéressantes.

Exemple

{
 "payment": {
  // ...
   "custom_data": {
      "scoring": {
         "departure_date": "2021-12-19",     // ISO 8601
         "return_date": "2021-12-22",        // ISO 8601
         "destination_name": "Lisbonne",     // string 
         "destination_country": "PT",        // ISO Alpha-2
         "refund_policy": "refundable",      // string
         "passengers": {
           "adult_count": 2,                 // int
           "children_count": 0,              // int
           "infant_count": 0                 // int
         },
         "hosting": {
           "room_type": "double",            // string
           "nights": 7,                      // int
           "category": 4                     // int
         },
         "flight": {
           "main_departure_company": "AF",   // string max 3 characters
           "departure_airport": "CDG",       // IATA code on 3 characters
           "arrival_airport": "LIS",         // IATA code on 3 characters
           "has_transfers": "false",         // Boolean "true" or "false"
           "round_trip": "true",             // Boolean "true" or "false"
           "travel_class": "economy"         // Should be the best class among the possible values
         },
         "insurance": {
           "name": "Assurance Multirisques", // string  max 150 characters
           "price": 5812                     // int in cents
         },
         "activity": "concert",              // string 
         "loyalty_program": {
           "has_loyalty": "true",            // Boolean "true" or "false"
           "name": "vip"                     // string
         }
      }
   },
  // ...
 }
}