Paiements Konbini

Pour commencer, vous avez besoin d’un compte Stripe. Inscrivez-vous.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Pour représenter votre intention d’encaisser le paiement d’un client, Stripe utilise un objet PaymentIntent qui suit les changements d’état depuis la création du PaymentIntent Konbini jusqu’à son exécution.

Créez un PaymentIntent sur votre serveur en précisant un montant et la devise jpy (Konbini ne prend pas en charge d’autres devises). Si votre intégration inclut déjà l’API Payment Intents, ajoutez konbini à la liste des types de moyens de paiement valides pour votre PaymentIntent.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=jpy \
  -d "payment_method_types[]"=konbini \
  -d "payment_method_options[konbini][product_description]"="Tシャツ" \
  -d "payment_method_options[konbini][expires_after_days]"=3

Récupérer la clé secrète du client

Le PaymentIntent contient une clé secrète à utiliser côté client pour finaliser le processus de paiement en toute sécurité. Vous pouvez adopter différentes approches pour transmettre cette clé secrète côté client.

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Options supplémentaires de moyens de paiement

Les options de moyens de paiement peuvent être définies dans les options des moyens de paiement sous la clé konbini.

Expiration

Les paiements Konbini en attente expirent juste avant minuit (23 h 59 m 59 s JST) à la date donnée. Par exemple, si le paramètre expires_after_days est défini sur 2 et que le PaymentIntent est confirmé le lundi, le paiement Konbini en attente expirera le mercredi à 23 h 59 m 59 s heure du Japon (UTC+9).

Le paramètre expires_at est un horodatage Unix exprimé en secondes. Si cette valeur est définie à moins de 30 minutes de l’heure actuelle ou si la confirmation du PaymentIntent est effectuée moins de 30 minutes avant l’heure d’expiration, une erreur sera renvoyée.

Les paramètres expires_after_days et expires_at s’excluent mutuellement. Une erreur sera renvoyée s’ils sont tous les deux définis. Ils sont également facultatifs, donc si aucun de ces paramètres n’est défini, la date d’expiration par défaut de 3 jours après la création du PaymentIntent s’appliquera à 23 h 59 heure du Japon (UTC+9).

Gestion des erreurs

Les requêtes concernant la création, la mise à jour et la confirmation de PaymentIntents sont susceptibles d’échouer. Vous pouvez identifier la valeur error de la réponse de l’API pour en déterminer la raison. Ensuite, dans de nombreux cas, soumettez de nouveau votre requête ou corrigez l’erreur. Si vous indiquez une valeur pour l’option de moyen de paiement confirmation_number, vous pourriez notamment vouloir traiter les codes d’erreur spécifiques que nous vous renvoyons. Pour plus de détails, consultez la page consacrée aux numéros de confirmation.

Le moyen de paiement peut parfois devenir indisponible en raison de pannes, de maintenances programmées ou de vos habitudes d’utilisation. Pour plus de détails, consultez la page consacrée à la gestion des problèmes de disponibilité temporaires.

Créez un formulaire de paiement côté client pour recueillir les informations de facturation du client :

L’exemple de formulaire présenté ici recueille également le numéro de téléphone, lequel sera utilisé comme numéro de confirmation fourni par le client.

<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <div class="form-row">
    <label for="phone">
      Phone Number
    </label>
    <input id="phone" name="phone" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with Konbini</button>
</form>

Lorsqu’un client clique pour payer avec Konbini, utilisez Stripe.js pour soumettre le paiement à Stripe. Stripe.js est notre bibliothèque JavaScript de base pour la création de tunnels de paiement.

Intégrez le script Stripe.js à votre page de paiement en l’ajoutant entre les balises head de votre fichier HTML.

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Créez une instance de Stripe.js avec le code JavaScript suivant sur votre page de paiement.

// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

Utilisez stripe.confirmKonbiniPayment et la clé secrète du client de l’objet PaymentIntent que vous avez créé à l’étape 2 pour envoyer les informations de facturation du client.

À la confirmation, Stripe ouvrira automatiquement une fenêtre modale afin d’afficher les instructions associées au paiement Konbini pour votre client.

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmKonbiniPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
      payment_method_options: {
        konbini: {
          confirmation_number: document.getElementById('phone').value.replace(/\D/g,''),
        },
      },
    }
  );
  // Stripe.js will open a modal to display the Konbini payment instructions to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});

Options supplémentaires de moyens de paiement

Lors de la confirmation d’un PaymentIntent Konbini, d’autres options de moyens de paiement peuvent être définies dans les options des moyens de paiement sous la clé konbini.

Numéros de confirmation

Pour finaliser leur paiement, vos clients devront se référer au confirmation_number. Si vous choisissez de définir cette valeur ou de laisser vos clients la définir, nous vous suggérons d’utiliser le numéro de téléphone du client. Un confirmation_number peut également être déterminé lors de la création du PaymentIntent côté serveur, mais il est en général défini par le client lors de la confirmation du PaymentIntent. La valeur définie lors de la création du PaymentIntent peut être modifiée jusqu’à la confirmation du PaymentIntent.

Si un confirmation_number défini a trop d’occurrences dans les transactions en cours du commerce, il pourrait être rejeté au moment de la confirmation du PaymentIntent. Dans ce cas, le code d’erreur renvoyé serait alors payment_intent_konbini_rejected_confirmation_number. Ce message ne s’affiche que lors de la confirmation d’un PaymentIntent.

Stripe bloque tous les numéros de confirmation composés uniquement de zéros lors de la création, de la modification et de la confirmation du PaymentIntent. Vérifiez que vous n’utilisez pas cette valeur et que vous n’autorisez pas vos clients à l’utiliser.

Gestion des erreurs

La confirmation d’un PaymentIntent côté client peut aussi échouer. Vous devez consulter la valeur error pour en déterminer la raison. Vous pourrez ainsi montrer l’erreur à votre client ou la corriger et essayer de nouveau.

Konbini est un moyen de paiement à notification différée, ce qui signifie que les fonds ne sont pas disponibles immédiatement. Les clients ne sont pas obligés de procéder immédiatement au règlement dans un magasin de proximité après avoir finalisé la commande.

Une fois le paiement Konbini effectué, Stripe envoie un événement payment_intent.succeeded. Utilisez le Dashboard ou créez un gestionnaire de webhook afin de recevoir ces événements et d’exécuter des actions. Exemples d’actions : envoyer un e-mail de confirmation de commande à votre client, enregistrer la vente dans une base de données ou lancer un flux de livraison.

S’il peut être établi avec certitude qu’un paiement Konbini en attente n’a pas été finalisé (généralement, environ une heure après sa date/heure limite d’expiration), Stripe envoie un événement payment_intent.payment_failed.

Recevoir des événements et exécuter des actions

Manuellement

Utilisez le Dashboard Stripe pour consulter tous vos paiements Stripe, envoyer des reçus par e-mail, gérer les virements et relancer les paiements en échec.

• Afficher vos paiements tests dans le Dashboard

Code personnalisé

Créez un gestionnaire de webhooks pour écouter des événements et créer des tunnels de paiement asynchrones personnalisés. Testez et déboguez votre intégration de webhooks en local, grâce à l’interface de ligne de commande Stripe.

• Créer un webhook personnalisé

Lors des tests, définissez payment_method.billing_details.email sur les valeurs suivantes lorsque vous appelez stripe.confirmKonbiniPayment pour tester différents scénarios. Vous pouvez effectuer vos tests avec un numéro de confirmation spécial et/ou un modèle d’e-mail. Si les deux sont fournis, le numéro de confirmation spécial s’applique.

Pour tester la gestion des erreurs touchant au numéro de confirmation, vous pouvez utiliser les valeurs suivantes pour payment_method_options[confirmation_number] :

• 01234567890 génère un code d’erreur payment_intent_konbini_rejected_confirmation_number.
• 00000000000 génère un code d’erreur de validation générique. Cette erreur peut être évitée dans votre intégration à l’aide de la prévalidation.