Webbshop med PayPal


Ansvarsfriskrivning – Jag kan tyvärr inte garantera att den här artikeln resulterar i en felfri och säker applikation, och det är därför ditt ansvar att kontrollera din kod mot dokumentationen.

I den här artikeln ska vi skapa en – webbshop med PayPal och applikationen kommer att baseras på Classic API. Som du kanske såg i förra avsnittet av den här serien – Skapa Din Egen Nätbutik, så finns det tre steg i en transaktion på nätet:

  1. Kundvagn > ska samla in information om köpet, som kortnummer, adress, namn mm.
  2. Betalningsgateway > krypterar informationen och skickar den till säljarkonto
  3. Säljarkonto > processar informationen och sätter in pengarna på kontot

Vi kommer att använda oss av PayPal:s säljarkonto i den här artikeln.

 

Utvecklingsprocess

Utvecklingsprocessen för en applikation som använder PayPal:s API, har följande steg:

  1. Registrera dig som PayPal utvecklare.
  2. Integrera PayPal-funktionalitet till din webbplats och eventuella mobila applikationer.
  3. Testa dina PayPal transaktionsrutiner i PayPal:s Sandbox.
  4. Gå live med applikationen.
  5. Underhålla och uppgradera applikationen.

 

 

Skapa Utvecklar-konto

Så, till att börja med behöver du skapa ett utvecklar-konto hos PayPal, och du kan göra det här. Där behöver du sedan skapa autentiseringsuppgifter, vilket du kan se hur du ska göra här. Det finns två typer av autentiseringsuppgifter:

  • Signature API autentiseringsuppgifter
  • Certificate API autentiseringsuppgifter

Båda kan användas men PayPal rekommenderar Certificate av säkerhetsskäl. Båda varianterna innehåller tre autentiserings-värden:

  • API Användarnamn
  • API Lösenord
  • Certifikat

Det är dessa som skickas tillsammans med anrop till PayPal API.

Tänk på! Du måste ha ett PayPal Business-konto för att göra anrop till PayPal:s live servrar.

 

Olika Betalningsalternativ

PayPal har ett antal olika betalningsalternativ och det gäller att välja den som passar bäst för just din sida. Men detta kan vara minst sagt förvirrande, då det finns så många alternativ.

 

  • Express Checkout – Med den främsta PayPal tjänsten: Express Checkout kan du få betalningar utan att ha ett konto och utan att behöva fylla speciella kriterier förutom att verifiera ditt PayPal konto (antingen via ett bankkonto eller ett kreditkort). Tidigare kunde man endast ta Express Checkout betalningar från registrerade PayPal-användare, men PayPal har lagt till en kreditkorts alternativ för icke-PayPal-användare, vilket gör denna tjänst tillgänglig för praktiskt taget vem som helst som har ett av dom större kreditkorten (VISA, MasterCard, osv.)
    • Tänk på: Express Checkout processen sker på PayPals plattform och kan därför aldrig bli helt integrerade i din webbplats användargränssnitt.
  • Direct Checkout – Direktbetalnings metoden gör det möjligt att ta emot kreditkortsbetalningar direkt via ett API-anrop. Detta gör att du kan genomföra hela betalningsprocessen på din webbplats, vilket möjliggör en mer komplett shoppingupplevelse för kunderna.
  • Recurring Payments – Detta gör att du kan ställa in ett återkommande transaktion (dvs. en abonnemangs betalning).
  • Mass Payments – Denna metod gör att man kan föra över pengar till flera konton på samma gång.
  • Adaptive Payments – Här är ett annat API för att skicka pengar till flera mottagare, med vissa skillnader från Massbetalnings API:n.

Listan är inte helt komplett, men den innehåller dom populäraste alternativen (se dokumentationen för fler produkter).

 

 

Att Göra API Anrop

PayPal stödjer två huvudsakliga format över HTTP, nämligen: NVP och SOAP. NVP står för ”Name, Value Pair”, och SOAP står för ”Simple Object Access Protocol”. Jag kommer att använda mig av NVP, eftersom SOAP trots sitt namn har ett relativt komplex syntax.

Var och en a dessav API-metoder har olika parametrar, men de båda delar på vissa grundläggande parametrar, som används för att identifiera API kontot och underteckna transaktionen.

Dessa innefattar:

  • USER Din PayPal API användarnamn.
  • PWD Din PayPal API lösenord.
  • VERSION Versions nummer för NVP API service; 95.0 (som är den senaste vid skrivande stund).
  • SIGNATURE Din PayPal API signatur sträng. Denna parameter är valfri om man använder ett certifikat för autentisering.
  • Den sista parameter som krävs är METHOD, vilken deklarerar den API metod vi anropar.

 

Klass för anrop

Anrop görs över HTTPS. Vi använder cURL för att bygga förfrågan, och kapslar in hela processen i en klass:

Svaret tillbaka kommer att vara i NVP-format, och vi formatera om den till en array innan vi returnerar den.

Parameter ACK innehåller status för förfrågan:

Success

..eller:

SuccessWithWarning

…när förfrågan lyckas, och:

Error

…eller:

Warning

… när förfrågan misslyckas.

En förfrågan kan misslyckas av många anledningar, och det finns många olika skäl för varje API-metod, och dessa beskrivs i detalj i manualen. Vi ska gå igenom sätt att hantera dem lite senare. Kom ihåg att parametervärdena är skiftlägeskänsliga (skiljer på stora och små bokstäver).

 

Express Checkout

En av de mest populära API är Express Checkout, som gör att du kan ta emot betalningar utan att öppna en Website Payments Pro-konto (som endast är tillgänglig för verifierada USA konton) eller hosta själva transaktionen själv (vilket kräver ytterligare säkerhet).

Express Checkout processen fungerar på följande sätt:

1. Vi förfrågar efter en checkout token från PayPal med hjälp av transaktionsuppgifter;
2. Om det lyckas, ska vi omdirigera användaren till PayPal Checkout tillsammans med den mottagna TOKEN.
3. Användaren slutför eller avbryter betalningen på PayPal-plattformen och omdirigeras Tillbaka till Vår hemsida;
4. Vi slutför transaktionen, antingen när användaren omdirigeras tillbaka eller via en Instant Payment Notification (IPN).

PayPal - Express Checkout process

PayPal – Express Checkout process

 

 

 

1. Begär Checkout Token

Vi initiera Express Checkout processen genom att skicka in orderuppgifter till PayPal API, och får då tillbaka en token sträng som identifierar ordern. Denna token ska användas i nästa steg när vi ska omdirigera användaren till PayPal.

Här följer de parametrar som krävs:

  • METHOD
    Detta är API metod som vi använder (dvs. SetExpressCheckout).
  • RETURNURL
    Den URL som användaren kommer att omdirigeras till efter att betalningen är klar.
  • CANCELURL
    Den URL som användaren kommer att omdirigeras till efter att ha avbrutit betalningsprocessen.
  • PAYMENTREQUEST_0_AMT
    Transaktionens totala beloppet. Detta måste ha två decimaler och decimaltecknet är en punkt, och den valfria tusentalsavgränsare måste vara ett kommatecken.
  • PAYMENTREQUEST_0_ITEMAMT
    Den totala kostnaden för objekten i ordning, exklusive frakt, skatter och andra kostnader. Om det inte finns några extra kostnader, så borde det vara samma värde som PAYMENTREQUEST_0_AMT.

Vi kan ange ytterligare parametrar att lägga till mer information om ordern, varav vissa har standardvärden:

  • PAYMENTREQUEST_0_CURRENCYCODE
    Betalnings valuta, en kod på tre bokstäver. Standard är USD, för Svenska kronor är det SEK och du hittar en lista över giltiga koder på sidan Currency Codes i dokumentationen.
  • PAYMENTREQUEST_0_SHIPPINGAMT
    De totala fraktkostnaden för denna order.
  • PAYMENTREQUEST_0_TAXAMT
    Det totala skattebeloppet för denna order. Detta krävs om per-post skatten specificeras (se nedan).
  • PAYMENTREQUEST_0_DESC
    Order beskrivning.

Vi kan även lägga till information om enskilda artiklar i ordern:

  • L_PAYMENTREQUEST_0_NAMEm
    Artikelns namn.
  • L_PAYMENTREQUEST_0_DESCm
    Artikelns beskrivning.
  • L_PAYMENTREQUEST_0_AMTm
    Artikelns kostnad.
  • L_PAYMENTREQUEST_0_QTYm
    Mängden av en artikel

Variableln m identifierar en enskild artikel. (Använd samma variabel för alla detaljer i samma artikel.)

Det finns många andra valfria parametrar, som finns i API-dokumentationen. Vi kommer att använda metoden request() som vi skrev i klassen Paypal, för att bygga anropet till SetExpressCheckout:

 

2. Omdirigera till PayPal

Om anropet till metoden är framgångsrikt, kommer vi att få en Checkout token som finns i TOKEN parametern av respons-arrayn.

Användaren går nu igenom köpprocessen på PayPals webbplats. När PayPal bekräftar eller avbryter transaktionen, kommer användaren att återvända till en av de webbadresser som vi har angett i förfrågan.

 

 

3. Slutför Transaktion

Förutsatt att användaren bekräftar transaktionen, kommer dom att omdirigeras till vår hemsida genom PayPal. Nu bör vi använda två API metoder: DoExpressCheckoutPayment som kommer att slutföra transaktionen, men innan dess, kanske vi vill kanske få ytterligare information om köparen med hjälp av GetExpressCheckoutDetails.

PayPal omdirigerar användaren tillbaka från köpet tillsammans med checkout token, som vi kommer att använda för att anropa dessa metoder. Denna token kommer att finnas tillgänglig i URL-query parametern via token parametern. Vi kommer att kontrollera för dess existens i bekräftelse URL och sedan skicka våra API anrop om vi hittar den.

GetExpressCheckoutDetails metod krävde endast checkout
token. DoExpressCheckoutPayment kräver ett par ytterligare parametrar:

  • PAYMENTREQUEST_0_PAYMENTACTION
    Detta är åtgärden betalningen. Det ska vara inställd på Sale om vi inte har angett en annan åtgärd i SetExpressCheckout metoden (möjliga värden inkluderar Authorization och Capture).
  • PAYERID
    Detta är en unik identifikation för PayPal-konto. Även detta, returneras i URL-query parametrar (i PAYERID parameter) och kan även hämtas från detaljerna som returneras av GetExpressCheckoutDetails.

 

 

Direkt betalning

Med Direct Payment API kan man ta emot betalningar direkt på sin webbplats/applikation, vilket ger fullständig kontroll över utcheckningsprocessen. PayPal tenderar att pusha på användare att registrera och använda ett PayPal-konto, vilket ju är förståeligt men det strider mot våra intressen, som ju är att göra betalningsprocessen som smärtfri och tydlig som möjligt för våra kunder. Av denna anledning är full kontroll över utcheckningen att föredra, och det ger oss också fler alternativ för att optimera försäljningen och genererar mer försäljning.

PayPal - Direct Payment

Processen för PayPals Direct Payment

Processen är lite enklare än Express Checkout, eftersom hela interaktionen sker på vår egen hemsida, och vi behöver endast utföra ett API-anrop för att bearbeta en normal betalning: DoDirectPayment.

Tips: Ett par fler API begäran krävs om man vill utföra en transaktion som faktureras i efterhand (till exempel när man skickar produkten eller bekräftar odrertillgänglighet). Dessa skulle vara Authorization & Capture API metoder, som jag inte kommer gå igenom i det här inlägget, men alternativet finns.

 

doDirectPayment

Direkt betalning kräver andra parametrar än Express Checkout. Medan parametrar för transaktionsdetaljer liknar varandra, kräver metoden även kreditkort och adressinformation.

doDirectPayment grundläggande parametrar:

  • METHOD
    Detta är DoDirectPayment.
  • IPADDRESS
    Detta är IP-adressen för kunden. I PHP, kan vi hämta det med hjälp av superglobaln $_SERVER[‘REMOTE_ADDR’]. Du måste göra lite mer arbete för att få IP-adress när det handlar uppställningar som har en proxy mellan PHP processen och utanför nätet (t.ex. nginx).
  • PAYMENTACTION
    Detta är den typ av åtgärder som vi vill utföra. Ett värde på Sale indikerar en omedelbar transaktion. Värdet Authorization indikerar att denna transaktion inte kommer att utföras omedelbart, utan snarare kommer att fångas senare använder Authorization & Capture API nämnde tidigare.

Kreditkortsuppgifter:

  • CREDITCARDTYPE
    Kredit-korttyp (Visa, Mastercard, etc.). Se API-dokumentation för hela listan.
  • ACCT
    Den kreditkortsnummer. (Inte du älskar dessa förkortade nyckelnamn?) Detta måste överensstämma med den speciella formatet kortets typ.
  • EXPDATE
    Den utgångsdatum, i MMÅÅÅÅ format (dvs ett tvåsiffrigt månad och ett år fyrsiffrigt, som en sträng).
  • CVV2
    The ”kortverifieringsvärdet” eller säkerhetskod, som det ibland kallas.
  • Information om betalaren och adressparametrar:
  • FIRSTNAMELASTNAME
    Betalarens förnamn och efternamn, respektive (i separata fält). Du kan också ange en e-postadress i ett e-post parameter, men det är inget krav.
  • CITY, STATE, COUNTRYCODE, ZIP
    Stad, stat, landskod (kod på två bokstäver) och postnummer är delar av adressen som alla behövs.
  • STREET, STREET2
    Skapar två linjer för adressen (endast det första krävs).

Denna adress kommer att användas i address verification system (AVS). Du får en specifik felkod om en transaktion har misslyckats på grund av en adressverifierings misslyckande.

Betalningsinformation parametrarna är desamma som de för Express Checkout, men med lite olika namn (AMT, ITEMAMT, CURRENCYCODE, SHIPPINGAMT, TAXAMT och fallande) och utan PAYMENTREQUEST_0_ prefix. Se föregående avsnitt eller API-dokumentation för specifika detaljer om dem.

Likaså artikelinformation parametrar liknande dem i Express Checkout. Dessa inkluderar L_NAMEm, L_DESCm, L_AMTm och L_QTYm, vilket ger dig detaljerad kontroll över posten detaljer i ordning sammanfattningen. Den m heltal variabel används för att redovisa flera objekt (ersätt med 0, 1 och så vidare för numrerade poster i ordning). Se API-dokumentationen för en omfattande lista med artikelinformation.

 

Utföra Transaktion

Att sända en en query med vår funktion request() är mycket likt GetExpressCheckoutToken. Vi passerar alla parametrar in i queryn fungerar exakt som förut, fast med metod satt till DoDirectPayment.

Det finns gott om parametrar, men dom är relativt enkla.

 

Felhantering

I en perfekt värld skulle detta avsnitt inte ens existerar. I verkligheten kommer du att hänvisa till det ganska mycket. PayPal kan misslyckas en transaktion för en mängd olika skäl, inte alla som kan du kontrollera.

Den $responsvariabel som vi återvänt från vår paypalApiRequest() funktionen kan innehålla ett annat värde än Success för ACK parameter. Detta värde kan vara:

  • Success
    Indikerar en lyckad operation.
  • SuccessWithWarning
    Indikerar en framgångsrik verksamhet och att meddelanden returneras i det svar som du bör undersöka.
  • Failure
    Indikerar en misslyckad operation, och att svaret innehåller en eller flera felmeddelanden som förklarar misslyckandet.
  • FailureWithWarning
    Indikerar en misslyckad operation, och att meddelanden returneras i det svar som du bör undersöka.
    Detta ger oss två framgångs status och två fel status. Den mock koden ovan tester för Success värdet bara, men vi kunde ändra det för att leta efter SuccessWithWarning också; och kom ihåg att vi måste ta reda på vad varningen är. Ett vanligt scenario är att en Direktbetalnings avgift har tagits med framgång, men kreditkortsföretaget svarar att transaktionen har misslyckats, oavsett orsak.

Fel från PayPal returneras i responsen som fyra parametrar:

  • L_ERRORCODE0
    En numerisk felkod, som kan refereras mot PayPal’s error kodlista (som är omfattande).
  • L_SHORTMESSAGE0
    En kort felmeddelande som beskriver problemet.
  • L_LONGMESSAGE0
    En längre felmeddelande som beskriver problemet.
  • L_SEVERITYCODE0
    Svårighetsgrad.

Noll-delen i dessa parametrar är ett ökande heltal för multipla felmeddelande (1, 2, etc.).

Här är några vanliga fel du kan stöta på:

  • 10002
    Autentisering eller tillstånd misslyckades. Detta tyder oftast ogiltiga API meriter eller referenser som inte matchar den typ av miljö du arbetar i (t.ex. en levande eller sandlåda miljö).
  • 81 ***
    Saknad parameter. Det finns en hel del av dessa, allt börjar med 81. Varje hänvisar till en specifik obligatorisk parameter som saknas i förfrågan.
  • 104 **
    Ogiltigt argument. Detta tyder på att en av de medföljande parametrar har ett ogiltigt värde. Varje argument har specifika fel, allt börjar med 104. En vanlig man är 10413, som innebär att den totala kostnaden för de varukorg poster matchar inte beställningens belopp (dvs. den totala mängden parametern, AMT, inte lika posterna totala plus sjöfart, hantering, skatter och andra avgifter).

 

Ta Hand om Felmeddelanden!

PayPal:s felmeddelanden varierar och kan innehålla privat information som du garanterat inte vill att dina användare att se (t.ex. en ogiltig försäljar-konfiguration). Om så är fallet, ska man inte visa dessa felmeddelanden direkt till användarna, även om vissa av dem kan vara användbara.

I de flesta fall skulle jag göra följande:

  1. Sätt upp en vit-lista rad fel som kan visas på ett säkert sätt (t.ex. en saknad kreditkortsnummer och utgångsdatum);
  2. Kontrollera svarskoden mot den arrayen;
  3. Om felmeddelandet inte är i den vita listan, visa ett generiskt felmeddelande, till exempel ”Ett fel inträffade under hanteringen av din betalning. Försök igen om några minuter, eller kontakta oss om detta är en återkommande fråga. ”

Om ett fel inte finns i den vita-listade arrayn, ska man logga det till en fil på servern och skicka ett mail till administratören, tillsammans med alla detaljer så att denne känner till misslyckade betalningar. Att loggar PayPal förfrågningar och svar är god praxis oavsett om dom innehåller felmeddelanden, så att man kan övervaka och felsöka betalnings misslyckanden.

 

Okej, det här borde få dig att komma igång med dom två populäraste PayPal alternativen Express Checkout och Direct Checkout. Till nästa gång, koda smart 😉

 

Ansvarsfriskrivning – Jag kan tyvärr inte garantera att den här artikeln resulterar i en felfri och säker applikation, och det är ditt ansvar att kontrollera din kod mot dokumentationen.

 

Huvudsaklig Källa

Lämna en kommentar

E-postadressen publiceras inte. Obligatoriska fält är märkta *