Come funziona l'API Payment Request

Scopri come funziona ad alto livello l'API Payment Request.

Eiji Kitamura

API Payment Request

Quando un cliente tenta di acquistare qualcosa dal tuo sito web, il sito deve chiedere al cliente di fornire i dati di pagamento e, facoltativamente, altre informazioni come la preferenza di spedizione. Puoi farlo in modo semplice e rapido utilizzando l'API Payment Request (API PR).

Struttura di base

La creazione di un oggetto PaymentRequest richiede due parametri: metodi di pagamento e dettagli di pagamento. Inoltre, un terzo parametro delle opzioni di pagamento è facoltativo. Una richiesta di base potrebbe essere creata come segue:

const request = new PaymentRequest(paymentMethods, paymentDetails);

Vediamo come viene creato e utilizzato ogni parametro.

Metodi di pagamento

Il primo parametro, paymentMethods, è un elenco di metodi di pagamento supportati in una variabile array. Ogni elemento dell'array comprende due componenti, supportedMethods e, facoltativamente, data.

Per supportedMethods, il commerciante deve specificare un identificatore del metodo di pagamento, come https://bobbucks.dev/pay. L'esistenza e i contenuti di data dipendono dai contenuti di supportedMethods e dal design del fornitore di app di pagamento.

Entrambe le informazioni devono essere fornite dal fornitore dell'app di pagamento.

// Supported payment methods
const paymentMethods = [{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: {
    ... // Optional parameters defined by the payment app provider.
  }
}];

Dettagli sul pagamento

Il secondo parametro, paymentDetails, viene trasmesso come oggetto e specifica i dettagli di pagamento della transazione. Contiene il valore obbligatorio total, che specifica l'importo totale dovuto dal cliente. Questo parametro può anche facoltativamente elencare gli articoli acquistati.

Nell'esempio riportato di seguito, vengono mostrati l'elenco facoltativo degli articoli acquistati (in questo caso un solo articolo), così come l'importo totale dovuto. In entrambi i casi, l'unità di valuta viene specificata con ogni singolo importo.

const paymentDetails = {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
};

Verificare se il metodo di pagamento è disponibile

Prima di richiamare la procedura di pagamento, il commerciante può verificare se l'utente e l'ambiente sono pronti per effettuare un pagamento.

La chiamata a canMakePayment() verifica se il browser supporta almeno un metodo di pagamento specificato nell'oggetto.

request.canMakePayment().then(result => {
  if (result) {
    // This browser supports the specified payment method.
  } else {
    // This browser does NOT support the specified payment method.
  }
}).catch(e => {
  // An exception
});

Scopri di più su PaymentRequest.canMakePayment() su MDN

Il metodo show()

Dopo aver impostato i due parametri e creato l'oggetto request come mostrato sopra, puoi chiamare il metodo show(), che mostra l'interfaccia utente dell'app di pagamento.

request.show().then(response => {
  // [process payment]
  // send to a PSP etc.
  response.complete('success');
});

L'aspetto dell'interfaccia utente delle app di pagamento dipende completamente dal fornitore di app di pagamento. Dopo che il cliente accetta di effettuare un pagamento, al commerciante viene trasmesso un oggetto JSON contenente tutte le informazioni necessarie per trasferire denaro. Il commerciante potrà quindi inviarlo al PSP per l'elaborazione del pagamento.

Infine, puoi chiudere l'interfaccia utente della richiesta di pagamento completando la procedura con response.complete('success') o response.complete('fail'), a seconda del risultato restituito dal PSP.

Successivo

Scopri di più sui pagamenti web.