Incorrect documentation for the demo API endpoint

[VizuaaLOG]

I'm trying to create a new order and transaction to charge a card, however, I keep receiving a 404 response from the API when posting https://demo-api.vivapayments.com/api/orders

The authentication is Basic using my merchant ID as the username and API key as the password.

I'm sending the following request:

{
    "tags": ["Website payment"],
    "email": "redacted",
    "Amount": 5354,
    "Phone": "redacted",
    "FullName": "Tom Erbe",
    "PaymentTimeOut": 86400,
    "RequestLang": "en-GB",
    "MerchantTrns": "#123",
    "CustomerTrns": "123"
}

But all I keep receiving is a 404 Not Found with no message provided.

This response is being received in both PHP via Curl and in Postman.

I'm finding the documentation very difficult to follow and not as helpful as it should be.

[VizuaaLOG]

The documentation is wrong with regards to what the URL is. The URL that works is actually https://demo.vivapayments.com/api/orders

This is what I mean with the documentation. It's always wrong or misleading making it a difficult product to recommend to any of our clients. The only reason it's being used currently is that it's required for this project.

[matthewrgourd]

Hi @VizuaaLOG Thanks for the heads-up. We are working on improving our documentation all the time so will take on board your comments. I'm sorry that you feel that way about our products which are evolving on a continuous basis and many people find useful / straightforward.

[theremon]

This issue should not be closed. The documentation needs serious updating. There is a mixup as far as the URLs are concerned - and the PHP demo scripts are obsolete as well. The aforementioned 'correct' URL https://demo.vivapayments.com/api/orders is valid for the v1 API and does not appear to work with v2 API calls since the authentication method has changed. I'm getting a 404 error as well for https://demo-api.vivapayments.com/orders (and the respective production URL as well). Is there a valid v2 API URL we can work with? If not, when do you expectto have it available since the 3DS methods should be available in a few days?

[VizuaaLOG]

@theremon From what I've seen (could be wrong here) the v2 API is primarily for charge tokens etc. so when requesting charge tokens and doing 3DS checks you use demo-api (this is handled automatically via the JS SDK). However, when creating orders, transactions etc. it's demo.

[theremon]

Hi there @VizuaaLOG

thanks for the reply. This wasn't quite clear in the documentation (I've seen references for both cases), but in any case I've tried that too - calling the old URL with the new credentials, but got an authentication error. Do you have any working examples by any chance for me to play with? Or is it that we need to call half of the workflow with the new procedures and half with the old? That sounds like quite a mess...

[VizuaaLOG]

@theremon Yes, from what I've seen you have to use both variants (I don't understand why and assume it's some weirdness with the demo systems).

Generate a token on your server, this assumes PHP and is using the Guzzle HTTP client for PHP. I believe it should be relatively straight forward to port to other languages though.

$client = new \GuzzleHttp\Client();
$res = $client->request('POST','https://demo-accounts.vivapayments.com/connect/token', [
        "auth"        => [ 'client_id', 'client_secret' ],
        "form_params" => [
            'grant_type' => 'client_credentials',
        ],
    ]
);

$result = json_decode($res->getBody());

// validate successful request

// $result now contains an access_token, this will need to be passed to your JS implementation

To get a charge token (this assumes you're using Viva's JS SDK) you setup the library with the https://demo-api.vivapayments.com endpoint:

VivaPayments.cards.setup({
    authToken: <access token generated on the server>,
    baseURL: 'https://demo-api.vivapayments.com',
    cardHolderAuthOptions: {
        cardHolderAuthPlaceholderId: 'viva_native_threed-secure-pane',
        cardHolderAuthInitiated: function () {
            threedModalElement.style.display = "block";
        },
        cardHolderAuthFinished: function () {
            setTimeout(function () {
                threedModalElement.style.display = "none";
            }, 1000);
        }
    }
});

Now you can perform a charge token request, once the form has been completed.

VivaPayments.cards.requestToken({
    amount: <amount in smallest value>,
    authenticateCardholder: true
}).then(function (response) {
    // response.chargeToken will be the token to parse to the server
}, function (error) {
    // error with the request
});

On your server you can then use the charge token to create an order, and then create a transaction with the order. The documentation for these API requests are correct I believe, but if you're having trouble with this also I can provide an example for both too 😄.

You use https://demo.vivapayments.com/api/orders and https://demo.vivapayments.com/api/transactions for that.

The orders and transactions APIs use the normal bearer auth method, same as when you requested the access token above.

When you move to production the documentation endpoints are correct I believe:

• Account - https://accounts.vivapayments.com/
• API - https://api.vivapayments.com/ (this does apply to both the server API calls, and the JS request token calls this time)

I have an implementation of the above working on a production e-commerce store.

I totally agree that the documentation needs a massive overhaul, took me 2 - 3 days ripping my hair out and trial and error to get this working. I was fortunate enough to be getting paid while doing it, so wasn't a 'waste' of my time, but was a waste on my employers' money!

Hope this helps! I know how frustrating it was for me. But once it's setup, it's been super reliable since.

Edit: Forgot to add, when testing payments use 4016000000040000012 as your card number. This is the only one I've found to perform a successful payment, and provide a reliable 3D Secure popup. 👍

[theremon]

@VizuaaLOG thank you

for taking the time to provide such a detailed reply - and on a Friday night too. I'm in your dept. It is a fact that it is quite unorthodox to have to use what is according to VIVA a "deprecated" API as before and just add a couple of functions from a "new" API, not to mention that no part of the documentation explains this properly. In the contrary, in the docs it is stressed that the URLs have changed - and I hope that the 404s we're getting from the production URLs will be resolved as we fully move the the 'new' API. Not to mention that your last edit with the card number is very important - it was more than expected after seeing the docs mess that the proposed test card would not be 3D Secure compatible. Anyway - time to get coding. I'll post the results here once I'm done.

Thanks again for all your trouble.

[VizuaaLOG]

@theremon no worries. Glad to help. If you want to see a working implementation of the above. I do have a woocommerce plugin on my profile that I'm in the process of writing. I decided to open source it as a native 2.0 implementation!

[theremon]

Oook... Things are looking "better"... As in "a total mess"... Got the initial auth token. Created the order. Got the requestToken. Then however, trying to create the transaction with the old API as discussed and data in the lines of:

OrderCode: [the code as provided by Viva when calling api/orders] Amount: "1000" CreditCard: array( 'Token' => the token from requestToken) Installments: 0 SourceCode: [my Source Id]

I get this: ErrorCode: 403 Error Text: Source [my Source Id] of merchant [Merchant Code] supports only native checkout

So... what now? I can get authenticated and so on, so forth, but cannot complete the procedure? This is getting really frustrating.

@VizuaaLOG , the credit card number you kindly provided, does not produce any popup or whatnot for further verification. Could I be missing something? I've added a simple

to my page (for testing purposes initially), I'm calling VivaPayments.cards.setup with the proper id, but nothing happens. I'll also quote your response above to the other issue I opened about the matter since this one does not immediately appear since it's still marked as 'closed'.

Any ideas would be greatly appreciated.

[VizuaaLOG]

Are you using your own demo Viva account? If so when you created the source in the dashboard did you select the native integration method?

What outcome do you get when sending a request to the orders API using (changing the email etc. where required):

{
    "tags": [ "Website payment" ],
    "email": "email@address.com",
    "Amount": 1000,
    "Phone": "phone number",
    "FullName": "Your Name",
    "PaymentTimeOut": 86400,
    "RequestLang": "en-GB",
    "MerchantTrns": "2345",
    "CustomerTrns": "Example 2345"
}

And then create a transaction using:

{
    "creditCard": { "token": "<charge token from the Viva JS lib>" },
    "orderCode": "<order code from above>"
}

This is all the data I send, I don't pass anything extra. The website on the dashboard is configured with HTTPS, the domain name and native as the implementation to use.

Also, the JS lib, are you loading https://www.vivapayments.com/web/checkout/v2/js and then config for this should link to a containing div where the 3D Secure form will render. However, you're responsible for showing/hiding the div when required.

[theremon]

Hello and thanks again so much for taking the time to help me with this. Yes, I'm using our demo account - don't have credentials for anyone else's... And yes, the source is a 'native' source. Funny thing is that the error says exactly that: "Source [my Source Id] of merchant [Merchant Code] supports only native checkout". We've used this source as a Native API source to set up our environment months ago and it worked fine, Same goes with our production source. Everything was fine until last week.

When I'm calling createOrder, I get a reply with the new error code. But when I try to create the transaction, I get the 403 error - something that hasn't happened in the past. Unfortunately I now cannot get any kind of response from the demo servers (especially https://demo-accounts.vivapayments.com/connect/token) either from my app or postman, so I can't give you detailed replies. If anything changes later on, I'll post again.

Edit: As for the JS lib, yes I'm loading the v2 and have set up the config to use my new div (it doesn't run otherwise):

VivaPayments.cards.setup({
    authToken: '[auth token as received with previous call to new API]',
    baseURL: 'https://demo-api.vivapayments.com/',
    cardHolderAuthOptions: {
        cardHolderAuthPlaceholderId: 'threed-secure-pane',
        cardHolderAuthInitiated: function() {
            ...
        },
        cardHolderAuthFinished: function() {
            ...
        }
    }
});

[VizuaaLOG]

Hmmm I'm not sure then. @matthewrgourd should be able to shed some light on this once they're back from the bank holiday weekend on Tuesday.

Not seen that error before and seems odd that it's complaining it only supports native checkout.

Are you able to post all of the code that's being used to send the API requests for the order, token and transaction? Of course, removing anything sensitive.

[theremon]

The code is not anything fancy... it's more or less as this (just edited to get it all together). Keep in mind that it works fine on production as we speak:

// Prepare POST data
$postargs = 'Amount=' . urlencode($amount) .
    '&RequestLang=' . urlencode($lang) .
    '&AllowRecurring='  . $allowRecurring .
    '&SourceCode=' . [SourceID] .
    '&Tags=' . json_encode($tags) .
    '&Email=' . urlencode($userProfile['UserEmail']) .
    '&Phone=' . urlencode($userProfile['PhoneNo']) .
    '&FullName=' . urlencode($userProfile['FirstName'] . ' ' . $userProfile['LastName']);

// Make the request - Just a simple curl call
$session = curl_init();
curl_setopt($session, CURLOPT_POST, true);
curl_setopt($session, CURLOPT_URL, 'https://demo.vivapayments.com/api/orders');
curl_setopt($session, CURLOPT_POSTFIELDS, $postargs);
curl_setopt($session, CURLOPT_HEADER, false);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
curl_setopt($session, CURLOPT_USERPWD, ___________);
curl_setopt($session, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($session, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($session, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
$response = curl_exec($session);

I believe that something went wrong when creating the v2 API credentials. Can't think of anything else. Guess we'll have to wait and see. I'll try contacting Viva in the morning and see if we manage to get anything useful from them.

[VizuaaLOG]

Yeah looks fine to me. If it's working okay in production then maybe an issue with your demo account on Viva's end. You may get a response from Viva tomorrow. I know @matthewrgourd would be able to help with this but I believe he is London based and we have a national holiday tomorrow so he may not respond until Tuesday.

Let me know if you work it out. Would be good to know what the issue may have been.

[theremon]

Sure will. Again, thanks for all your help and support. It is greatly appreciated!

[dpnevmatikos]

Hello @theremon and @VizuaaLOG Well there seems to be much confusion around the whole process of integrating with Native Checkout v2 and we're the ones to blame. Apologies for that. As @matthewrgourd said we're constantly trying to improve our APIs and the functionality provided. It is however, fair to say that there's much more work needed to be done.

Funny thing is that the error says exactly that: "Source [my Source Id] of merchant [Merchant Code] supports only native checkout"

Well this is indeed funny as Native Checkout v2 requires sources created with "Integration method" set to "Redirect" (see screenshot below). Can you please try creating a new source and then trying again?

Or is it that we need to call half of the workflow with the new procedures and half with the old? That sounds like quite a mess...

Yes. There are basically two different API sets within the Viva Wallet ecosystem. The "old" API uses basic authentication and is responsible (amongst other things) to create orders and process transactions. The "new" API uses bearer authentication and handles requests for card tokenization and the Native Checkout v2 API. Unfortunately, certain operations require the use of both of them. Needless to say that we're working towards an API which will unify both the "old" and the "new" under a single authentication scheme.

But once it's setup, it's been super reliable since.

Good to know and we plan to keep it that way. :)

Let me know if I can be of further assistance.

[VizuaaLOG]

@dpnevmatikos oh that makes sense actually. Completely missed that. So I don't pass the SourceCode prop through on the API requests which I assume causes it to use the default, which is redirection.

So assuming the Native implementation option is for the old V1 api then?

[dpnevmatikos]

@VizuaaLOG you can either use the default source code or create a new one. That's is up to you, SourceCode is a valid parameter for both the [POST] api/transactions and [POST] api/orders endpoints.

[theremon]

First of all, thanks for all the help @VizuaaLOG and @dpnevmatikos There are several things that got cleared up and finally we got our code to a working condition. Unfortunately, we haven't been able to test and verify anything concerning the 3DS verification procedure functionality as none of our tests have triggered the 3DS procedure. We tried with the Viva-suggested card (4111111111111111) and the one @VizuaaLOG suggested (4016000000040000012). Is there an 'official' (ie. Viva-suggested, supported and of course working!) credit card that can be used for testing the whole thing or not? This migration procedure has proven to be quite frustrating for what is essentially is an added authorization step, so please do something, clear it up and provide a valid, working solution.

[theremon]

Hey guys

we've been unable to trigger a 3DS check with the test cards suggested. Any chance we can sort this out so we can conclude our tests and wrap up? Are there any alternative cards we can use, or can the be configured to trigger 3DS checks (as has happened before) please?

Thanks

[VizuaaLOG]

Do none of the cards in this thread trigger it for you? I had the same but the card I provided has always worked for me and triggered the 3D secure check.

[theremon]

Hey there @VizuaaLOG

after some days of waiting, it finally worked and we seem to be ok all across the board now. Thanks for everything!