PartnerCard Payment: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
 
(40 intermediate revisions by 2 users not shown)
Line 4: Line 4:
With partner card payment a Barion partner can issue a plastic card that can be used to topup a Barion wallet or make a payment with it. For this the partner has to request a Barion API key. This API is only available for specific partners.
With partner card payment a Barion partner can issue a plastic card that can be used to topup a Barion wallet or make a payment with it. For this the partner has to request a Barion API key. This API is only available for specific partners.


The feature contains three major areas:
The feature contains four major areas:
* Card registration
# [[Remote_Identification|Identification of the customer]]
* Topup with the card
# [[PartnerCard_Payment#Card registration|Registering the partner card]]
* Payment with the card  
# [[PartnerCard_Payment#Topup|Topping up the customers wallet]]
# [[PartnerCard_Payment#Payment|Paying with the card]]


 
== Card registration ==
== Card registration process ==
[[File:Partner-card-process.jpg]]
[[File:Partner-card.jpg]]




Line 17: Line 17:
# '''Card preparation''': The partner requests a new card secret from the Barion API. This is stored on the card and used for authentication later. One card number can only be registered once. At this point the card is not attached to any Barion wallet.
# '''Card preparation''': The partner requests a new card secret from the Barion API. This is stored on the card and used for authentication later. One card number can only be registered once. At this point the card is not attached to any Barion wallet.
# '''Card issueing''': The previously registered card can be issued. This means that the card will be attached to a Barion wallett.
# '''Card issueing''': The previously registered card can be issued. This means that the card will be attached to a Barion wallett.
# '''Card activation''': The owner of the card must choose a PIN number that ensures another factor in the security protocol. This should be registered with the Barion API and '''must not'' be stored on the card itself.
# '''Card activation''': The owner of the card must choose a PIN number that ensures another factor in the security protocol. This should be registered with the Barion API and '''must not''' be stored on the card itself.


=== Card preparation example ===
=== Card preparation example ===
Line 24: Line 24:
{
{
   "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
   "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
   "PAN": "4657 3726 1490"
   "PAN": "4657 3726 1490 8885"
}
}
</pre>
</pre>
Line 41: Line 41:
   "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
   "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
   "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
   "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
   "OwnerLoginName": "[email protected]"
   "OwnerLoginName": "[email protected]",
  "OwnerPassword": "5tr0ng_Pa55W0rd"
}
}
</pre>
</pre>
Line 68: Line 69:
   "CardActivationWasSuccessful": true,
   "CardActivationWasSuccessful": true,
   "Errors": []
   "Errors": []
}
</pre>
=== PIN change example ===
'''Request'''
<pre>
{
  "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
  "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
  "CurrentPin":"1234",
  "NewPin":"8888"
}
</pre>
'''Response'''
<pre>
{
    "PinChangeSuccessful": true,
    "PrivateCardKey": "e8801cc5229f44e5b28a905efefce283",
    "Errors": []
}
}
</pre>
</pre>
Line 73: Line 93:
=== Related API endpoints ===
=== Related API endpoints ===


* [[PaymentCard_Prepare_v2|v2/PaymentCard/Prepare]]
* [[PartnerCard_Prepare_v2|v2/PartnerCard/Prepare]]
* [[PaymentCard_Issue_v2|v2/PaymentCard/Issue]]
* [[PartnerCard_Issue_v2|v2/PartnerCard/Issue]]
* [[PaymentCard_Activate_v2|v2/PaymentCard/Activate]]
* [[PartnerCard_Activate_v2|v2/PartnerCard/Activate]]
* [[PartnerCard_ChangePin_v2|v2/PartnerCard/ChangePin]]
* [[PartnerCard_Delete_v2|v2/PartnerCard/Delete]]
 
== Topup ==
 
In this process a customers wallet (identified by a card) can be topped up via a third party e-wallet (called a topup fascilitator in this model). This means that an e-money transfer will take place between two wallets.


== TopUp process ==
[[File:Topup-participants.jpg]]
TODO
== Payment process ==


The partner card payment uses the Barion PaymentGateway to prepare the payment. This means that the payment should first be prepared and than fulfilled.
To be able to topup an account with a partner card, the partner app has to call the <tt>[[Topup_FromWalletWithPartnerCard_v2|v2/Topup/FromWalletWithPartnerCard]]</tt> API endpoint. This will move the specified amount from the source wallett to the target wallet (card owners wallet). To be able to do this, the source wallets owner should have enough money for the specified amount and for the topup fee as well.
 
 
[[File:Topup.jpg]]
 
 
'''Example request'''
 
<pre>
{
    "PartnerKey": "f776efde-bd50-4755-a233-caa48cdf961f",
    "SourceWalletLoginName": "[email protected]",
    "PrivateCardKey": "2ba47cde700442f18639f47aa492a3b4",
    "CardPin": "1234",
    "Amount": 500,
    "Currency": "HUF",
    "Agent": {
"FirstName": "Steve",
"LastName": "Smith",
"Identifier": "[email protected]"
      },
      "Client": {
"FirstName": "Joe",
"LastName": "Smith",
"Identifier": "988475LA"
      }
}
</pre>
 
'''Example response'''
<pre>
{
    "WasTopUpSuccessful": true,
    "TopUpTransactionId": "356e532734fd43dc91d4d4f8b558d8b4",
    "Errors": []
}
</pre>
 
=== Releated API endpoints ===
*[[Topup_FromWalletWithPartnerCard_v2|v2/Topup/FromWalletWithPartnerCard]]
*[[Topup-StornoPartnerCardTopup-v2|v2/TopUp/StornoPartnerCardTopup]]
 
== Payment ==
 
The partner card payment uses the Barion PaymentGateway to prepare the payment. This means that the payment should first be prepared and than fulfilled. At this moment only e-money payment is supported. This means that the total of the payment must be available in the wallet of the payer.


[[File:Payment.jpg]]
[[File:Payment.jpg]]
Line 87: Line 155:
=== Preparing the payment ===
=== Preparing the payment ===


To prepare the payment the partner has to model a payment scenario. The easiest scenario is a simple immediate payment that can be configured as described on the [[Responsive_web_payment|Responsive Web Payment]] page.
To prepare the payment the partner has to model a payment scenario. The easiest scenario is a simple immediate payment that can be configured as described on the [[Responsive_web_payment|Responsive Web Payment]] page. At this point only the immediate e-money payment scenario is supported (no matter what the <code>FundingSources</code> property is set to).
 
'''Example preparation request'''
<pre>
 
{
    "POSKey": "ab9ebdba-e1bf-46a6-bf3c-4a3a38b95044",
    "PaymentType": "Immediate",
    "PaymentRequestId": "PAYMENT--001",
    "FundingSources": ["All"],
    "OrderNumber": "Order_01",
    "Currency": "HUF",
    "Transactions": [
        {
            "POSTransactionId": "TRANSACTION--01",
            "Payee": "[email protected]",
            "Total": 150000,
            "Comment": "Shipment 002",
            "Items": [ ]
        }
    ]
}
 
</pre>
 
'''Example reparation response'''
<pre>
{
  "PaymentId": "9361c11b72f548b9a21537d23f34ce20",
  "PaymentRequestId": "PAYMENT--001",
  "Status": "Prepared",
  "QRUrl": "https://api.barion.com/qr/generate?paymentId=9361c11b72f548b9a21537d23f34ce20&size=Large",
  "Transactions": [
    {
      "POSTransactionId": "TRANSACTION--01",
      "TransactionId": "12084502b4474188abec644207b9fa2e",
      "Status": "Prepared",
      "Currency": "HUF",
      "TransactionTime": "2017-06-02T08:33:48.118",
      "RelatedId": null
    }
  ],
  "RecurrenceResult": "None",
  "GatewayUrl": "https://secure.barion.com/Pay?Id=9361c11b72f548b9a21537d23f34ce20",
  "RedirectUrl": null,
  "CallbackUrl": null,
  "Errors": []
}
</pre>
 
=== Fulfilling the payment ===
 
To fulfill the payment you have to use the [[Payment_PayWithPartnerCard_v2|v2/Payment/PayWithPartnerCard]] endpoint and POST the <code>PaymentId</code> and the card information.
 
'''Example payment request'''
<pre>
{
  "PartnerKey" : "f776efdebd504755a233caa48cdf961f",
  "PrivateCardKey": "14b3c9133c2c4416af8806282e9f4b0e",
  "CardPin": "1234",
  "PaymentId": "9f51f0c209294f5a913d9304758defcd"
}
</pre>
 
'''Example payment response'''
<pre>
{
  "IsSuccessful": true,
  "PaymentId": "9f51f0c209294f5a913d9304758defcd",
  "PaymentRequestId": "PAYMENT--001",
  "PaymentStatus": "Succeeded",
  "Errors": []
}
</pre>
 
=== Related API endpoints ===
 
* [[Payment_PayWithPartnerCard_v2|v2/Payment/PayWithPartnerCard]]

Latest revision as of 08:35, 5 September 2017

Partner Card Payment

With partner card payment a Barion partner can issue a plastic card that can be used to topup a Barion wallet or make a payment with it. For this the partner has to request a Barion API key. This API is only available for specific partners.

The feature contains four major areas:

  1. Identification of the customer
  2. Registering the partner card
  3. Topping up the customers wallet
  4. Paying with the card

Card registration


The partner card registration contains three steps.

  1. Card preparation: The partner requests a new card secret from the Barion API. This is stored on the card and used for authentication later. One card number can only be registered once. At this point the card is not attached to any Barion wallet.
  2. Card issueing: The previously registered card can be issued. This means that the card will be attached to a Barion wallett.
  3. Card activation: The owner of the card must choose a PIN number that ensures another factor in the security protocol. This should be registered with the Barion API and must not be stored on the card itself.

Card preparation example

Request

{
   "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
   "PAN": "4657 3726 1490 8885"
}

Response

{
  "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
  "Errors": []
}

Card issueing example

Request

{
   "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
   "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
   "OwnerLoginName": "[email protected]",
   "OwnerPassword": "5tr0ng_Pa55W0rd"
}

Response

{
  "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
  "CardIssueWasSuccessful": true,
  "Errors": []
}

Card activation example

Request

{
   "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
   "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
   "CardPin": "1234"
}

Response

{
  "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
  "CardActivationWasSuccessful": true,
  "Errors": []
}

PIN change example

Request

{
  "PartnerKey" : "f776efde-bd50-4755-a233-caa48cdf961f",
  "PrivateCardKey": "b9c8c4c3e660484ca166a32f0ba584cf",
  "CurrentPin":"1234",
  "NewPin":"8888"
}

Response

{
    "PinChangeSuccessful": true,
    "PrivateCardKey": "e8801cc5229f44e5b28a905efefce283",
    "Errors": []
}

Related API endpoints

Topup

In this process a customers wallet (identified by a card) can be topped up via a third party e-wallet (called a topup fascilitator in this model). This means that an e-money transfer will take place between two wallets.

To be able to topup an account with a partner card, the partner app has to call the v2/Topup/FromWalletWithPartnerCard API endpoint. This will move the specified amount from the source wallett to the target wallet (card owners wallet). To be able to do this, the source wallets owner should have enough money for the specified amount and for the topup fee as well.



Example request

{
     "PartnerKey": "f776efde-bd50-4755-a233-caa48cdf961f",
     "SourceWalletLoginName": "[email protected]",
     "PrivateCardKey": "2ba47cde700442f18639f47aa492a3b4",
     "CardPin": "1234",
     "Amount": 500,
     "Currency": "HUF",
     "Agent": {
	"FirstName": "Steve",
	"LastName": "Smith",
	"Identifier": "[email protected]"
      },
      "Client": {
	"FirstName": "Joe",
	"LastName": "Smith",
	"Identifier": "988475LA"
      }
}

Example response

{
    "WasTopUpSuccessful": true,
    "TopUpTransactionId": "356e532734fd43dc91d4d4f8b558d8b4",
    "Errors": []
}

Releated API endpoints

Payment

The partner card payment uses the Barion PaymentGateway to prepare the payment. This means that the payment should first be prepared and than fulfilled. At this moment only e-money payment is supported. This means that the total of the payment must be available in the wallet of the payer.

Preparing the payment

To prepare the payment the partner has to model a payment scenario. The easiest scenario is a simple immediate payment that can be configured as described on the Responsive Web Payment page. At this point only the immediate e-money payment scenario is supported (no matter what the FundingSources property is set to).

Example preparation request


{
    "POSKey": "ab9ebdba-e1bf-46a6-bf3c-4a3a38b95044",
    "PaymentType": "Immediate",
    "PaymentRequestId": "PAYMENT--001",
    "FundingSources": ["All"],
    "OrderNumber": "Order_01",
    "Currency": "HUF",
    "Transactions": [
        {
            "POSTransactionId": "TRANSACTION--01",
            "Payee": "[email protected]",
            "Total": 150000,
            "Comment": "Shipment 002",
            "Items": [ ]
        }
    ]
}

Example reparation response

{
  "PaymentId": "9361c11b72f548b9a21537d23f34ce20",
  "PaymentRequestId": "PAYMENT--001",
  "Status": "Prepared",
  "QRUrl": "https://api.barion.com/qr/generate?paymentId=9361c11b72f548b9a21537d23f34ce20&size=Large",
  "Transactions": [
    {
      "POSTransactionId": "TRANSACTION--01",
      "TransactionId": "12084502b4474188abec644207b9fa2e",
      "Status": "Prepared",
      "Currency": "HUF",
      "TransactionTime": "2017-06-02T08:33:48.118",
      "RelatedId": null
    }
  ],
  "RecurrenceResult": "None",
  "GatewayUrl": "https://secure.barion.com/Pay?Id=9361c11b72f548b9a21537d23f34ce20",
  "RedirectUrl": null,
  "CallbackUrl": null,
  "Errors": []
}

Fulfilling the payment

To fulfill the payment you have to use the v2/Payment/PayWithPartnerCard endpoint and POST the PaymentId and the card information.

Example payment request

{
   "PartnerKey" : "f776efdebd504755a233caa48cdf961f",
   "PrivateCardKey": "14b3c9133c2c4416af8806282e9f4b0e",
   "CardPin": "1234",
   "PaymentId": "9f51f0c209294f5a913d9304758defcd"
}

Example payment response

{
  "IsSuccessful": true,
  "PaymentId": "9f51f0c209294f5a913d9304758defcd",
  "PaymentRequestId": "PAYMENT--001",
  "PaymentStatus": "Succeeded",
  "Errors": []
}

Related API endpoints